TSdlAsyncIOQueue
A queue of completed asynchronous I/O tasks.
When starting an asynchronous operation, you specify a queue for the new task. A queue can be asked later if any tasks in it have completed, allowing an app to manage multiple pending tasks in one place, in whatever order they complete.
Definition
Unit: Neslib.Sdl3.IO
Operators
| Name | Description |
|---|---|
| Equal(TSdlAsyncIOQueue, TSdlAsyncIOQueue) | Used to compare against another TSdlAsyncIOQueue. |
| Equal(TSdlAsyncIOQueue, Pointer) | Used to compare against nil. |
| Implicit | Used to set the value to nil. |
| NotEqual(TSdlAsyncIOQueue, TSdlAsyncIOQueue) | Used to compare against another TSdlAsyncIOQueue. |
| NotEqual(TSdlAsyncIOQueue, Pointer) | Used to compare against nil. |
Methods
| Name | Description |
|---|---|
| Create | Create a task queue for tracking multiple I/O operations. |
| Free | Destroy a previously-created async I/O task queue. |
| GetResult | Query the async I/O task queue for completed tasks. |
| Signal | Wake up any threads that are blocking in WaitResult. |
| WaitResult | Block until an async I/O task queue has a completed task. |
Operator Descriptions
Equal(TSdlAsyncIOQueue, TSdlAsyncIOQueue)
Used to compare against another TSdlAsyncIOQueue.
class operator Equal(const ALeft, ARight: TSdlAsyncIOQueue): Boolean; inline; static
Parameters
ALeft: TSdlAsyncIOQueue
ARight: TSdlAsyncIOQueue
Returns
Boolean
Equal(TSdlAsyncIOQueue, Pointer)
Used to compare against nil.
class operator Equal(const ALeft: TSdlAsyncIOQueue; const ARight: Pointer): Boolean; inline; static
Parameters
ALeft: TSdlAsyncIOQueue
ARight: Pointer
Returns
Boolean
Implicit(Pointer)
Used to set the value to nil.
class operator Implicit(const AValue: Pointer): TSdlAsyncIOQueue; inline; static
Parameters
AValue: Pointer
Returns
NotEqual(TSdlAsyncIOQueue, TSdlAsyncIOQueue)
Used to compare against another TSdlAsyncIOQueue.
class operator NotEqual(const ALeft, ARight: TSdlAsyncIOQueue): Boolean; inline; static
Parameters
ALeft: TSdlAsyncIOQueue
ARight: TSdlAsyncIOQueue
Returns
Boolean
NotEqual(TSdlAsyncIOQueue, Pointer)
Used to compare against nil.
class operator NotEqual(const ALeft: TSdlAsyncIOQueue; const ARight: Pointer): Boolean; inline; static
Parameters
ALeft: TSdlAsyncIOQueue
ARight: Pointer
Returns
Boolean
Method Descriptions
Create
Create a task queue for tracking multiple I/O operations.
Async I/O operations are assigned to a queue when started. The queue can be checked for completed tasks thereafter.
class function Create: TSdlAsyncIOQueue; inline; static
Exceptions
ESdlError: Raised on failure.
Returns
See Also
Remarks
It is safe to call this constructor from any thread
Free
Destroy a previously-created async I/O task queue.
If there are still tasks pending for this queue, this call will block until those tasks are finished. All those tasks will be deallocated. Their results will be lost to the app.
Any pending reads from SdlLoadAsync that are still in this queue will have their buffers deallocated by this function, to prevent a memory leak.
Once this function is called, the queue is no longer valid and should not be used, including by other threads that might access it while destruction is blocking on pending tasks.
Do not destroy a queue that still has threads waiting on it through WaitResult. You can call Signal first to unblock those threads, and take measures (such as waiting on a thread) to make sure they have finished their wait and won't wait on the queue again.
procedure Free; inline
Remarks
It is safe to call this method from any thread, so long as no other thread is waiting on the queue with WaitResult.
GetResult(TSdlAsyncIOOutcome)
Query the async I/O task queue for completed tasks.
If a task assigned to this queue has finished, this will return True and fill in AOutcome with the details of the task. If no task in the queue has finished, this function will return False. This function does not block.
If a task has completed, this function will free its resources and the task pointer will no longer be valid. The task will be removed from the queue.
It is safe for multiple threads to call this function on the same queue at once; a completed task will only go to one of the threads.
function GetResult(out AOutcome: TSdlAsyncIOOutcome): Boolean; inline
Parameters
AOutcome: TSdlAsyncIOOutcome
: Details of a finished task will be written here.
Returns
Boolean: True if a task has completed, False otherwise.
See Also
Remarks
It is safe to call this method from any thread
Signal
Wake up any threads that are blocking in WaitResult.
This will unblock any threads that are sleeping in a call to WaitResult for the specified queue, and cause them to return from that function.
This can be useful when destroying a queue to make sure nothing is touching it indefinitely. In this case, once this call 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 (perhaps by setting a flag to tell the threads to terminate and then waiting for a thread to finish to make sure they've done so).
procedure Signal; inline
See Also
Remarks
It is safe to call this method from any thread
WaitResult(TSdlAsyncIOOutcome, Integer)
Block until an async I/O task queue has a completed task.
This function puts the calling thread to sleep until there a task assigned to the queue that has finished.
If a task assigned to the queue has finished, this will return True and fill in AOutcome with the details of the task. If no task in the queue has finished, this function will return false.
If a task has completed, this function will free its resources and the task pointer will no longer be valid. The task will be removed from the queue.
It is safe for multiple threads to call this function on the same queue at once; a completed task will only go to one of the threads.
Note that by the nature of various platforms, more than one waiting thread may wake to handle a single task, but only one will obtain it, so ATimeoutMS is a maximum wait time, and this function may return False sooner.
This function may return False if there was a system error, the OS inadvertently awoke multiple threads, or if Signal was called to wake up all waiting threads without a finished task.
A timeout can be used to specify a maximum wait time, but rather than polling, it is possible to have a timeout of -1 to wait forever, and use Signal to wake up the waiting threads later.
function WaitResult(out AOutcome: TSdlAsyncIOOutcome; const ATimeoutMS: Integer): Boolean; inline
Parameters
AOutcome: TSdlAsyncIOOutcome
: Details of a finished task will be written here.
ATimeoutMS: Integer
: The maximum time to wait, in milliseconds, or -1 to wait indefinitely.
Returns
Boolean: True if task has completed, False otherwise.
See Also
Remarks
It is safe to call this method from any thread