Class AsyncIOQueue

Namespace

Sdl3Sharp.IO

Assembly

Sdl3Sharp.dll

Represents a queue for asynchronous I/O operations

public sealed class AsyncIOQueue : IDisposable

Inheritance

object

AsyncIOQueue

Implements

IDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Constructors

AsyncIOQueue()

Creates a new AsyncIOQueue

public AsyncIOQueue()

Exceptions

SdlException

The AsyncIOQueue could not be created

Methods

Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

public void Dispose()

~AsyncIOQueue()

protected ~AsyncIOQueue()

Signal()

Wakes up any threads waiting for an asynchronous I/O outcome (TryWaitForOutcome(out AsyncIOOutcome?, int)) from this queue

public void Signal()

Remarks

This method will unblock any threads that are sleeping in a call to TryWaitForOutcome(out AsyncIOOutcome?, int) for this queue, and cause them to return from that method.

This method can be useful when disposing a queue to make sure nothing is waiting on it indefinitely. In this case, once the call to this method completes, the caller should take measures to make sure any previously-blocked threads have returned from their wait and will not touch the queue again.

TryGetOutcome(out AsyncIOOutcome?)

Tries to get an asynchronous I/O outcome (AsyncIOOutcome) from this queue without blocking

public bool TryGetOutcome(out AsyncIOOutcome? outcome)

Parameters

outcome AsyncIOOutcome

The AsyncIOOutcome representing the result of a finished asynchronous I/O operation, when this method returns true; otherwise, null

Returns

bool

true, if there was a finished asynchronous I/O operation in the queue; otherwise, false

Remarks

If an asynchronous I/O operation assigned to this queue has finished, this method will return true and fill in outcome with the details of result of that operation. If no asynchronous I/O operation in the queue has finished, this method will return false immediately. This method does not block.

If an asynchronous I/O operation has finished, this method will clean up its internal resources, and then the operation will be removed from the queue.

It is safe for multiple threads to call this method on the same AsyncIOQueue instance at once; a finished asynchronous I/O operation will only be removed once and it's AsyncIOOutcome will only be returned to one of the threads.

TryWaitForOutcome(out AsyncIOOutcome?, int)

Tries to wait for an asynchronous I/O outcome (AsyncIOOutcome) from this queue

public bool TryWaitForOutcome(out AsyncIOOutcome? outcome, int timeoutMs = -1)

Parameters

outcome AsyncIOOutcome

The AsyncIOOutcome representing the result of a finished asynchronous I/O operation, when this method returns true; otherwise, null

timeoutMs int

The maximum time to wait for an outcome, in milliseconds, or -1 to wait indefinitely

Returns

bool

true, if there was a finished asynchronous I/O operation in the queue, or if an asynchronous I/O operation finishes before the queue was signaled or timed out; otherwise, false

Remarks

This method puts the caller thread to sleep until there an asynchronous I/O operation assigned to the queue that has finished.

If an asynchronous I/O operation assigned to this queue has finished, this method will return true and fill in outcome with the details of result of that operation. If no asynchronous I/O operation in the queue has finished until the queue was signaled or timed out, this method will return false.

If an asynchronous I/O operation has finished, this method will clean up its internal resources, and then the operation will be removed from the queue.

It is safe for multiple threads to call this method on the same AsyncIOQueue instance at once; a finished asynchronous I/O operation will only be removed once and it's AsyncIOOutcome will only be returned to one of the threads.

Please note that by the nature of some platforms, more than one waiting thread may wake to handle to outcome of a single asynchronous I/O operation, but only one thread will obtain it and it's call to this method will return true, while the return value of the other awoken threads will be false. So timeoutMs is a maximum wait time, and this method may return false sooner.

This method may return false sooner if there was a system error, the OS inadvertently awoke multiple threads, or if Signal() was called on the AsyncIOQueue instance to wake up all waiting threads without a finished asynchronous I/O operation.

A timeoutMs can be used to specify a maximum wait time, but rather than polling, it is possible to have a timeoutMs value of -1 (its default value) to wait indefinitely, and use Signal() to wake up the waiting threads later.