aio_suspend()

Updated: April 19, 2023

Wait for asynchronous I/O operations to be completed

Synopsis:

#include <aio.h>

int aio_suspend( const struct aiocb * const list[],
                 int nent,
                 const struct timespec * timeout );

Arguments:

list
A list of aiocb structures describing the asynchronous operations you want to wait for. Each aiocb structure must have been used in initiating an asynchronous I/O request via aio_read(), aio_write(), or lio_listio(). The list may contain NULL pointers, which aio_suspend() ignores.
nent
The number of entries in the list.
timeout
NULL, or a pointer to a timespec structure that specifies the maximum length of time you want to wait for.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

The aio_suspend() function suspends the calling thread until at least one of the asynchronous I/O operations referenced by the list argument has been completed, until a signal interrupts the function, or, if timeout isn't NULL, until the time interval specified by timeout has passed.

If any of the aiocb structures in the list correspond to completed asynchronous I/O operations (i.e., the error status for the operation isn't EINPROGRESS) at the time of the call, aio_suspend() returns without suspending the calling thread.

Returns:

0 if one or more of the asynchronous I/O operations have been completed, otherwise -1 (errno is set).

You can determine which asynchronous I/O operations were completed by scanning the associated error and return status, using aio_error() and aio_return().

Errors:

EAGAIN
No asynchronous I/O operation indicated in the list was completed in the time interval indicated by timeout.
EINTR
A signal interrupted the aio_suspend() function. Note that, since each asynchronous I/O operation may possibly provoke a signal when it's completed, this error return may be caused by the completion of one (or more) of the very I/O operations you're waiting on.

Classification:

POSIX 1003.1

Safety:  
Cancellation point Yes
Interrupt handler No
Signal handler Yes
Thread Yes

Caveats:

The first time you call an aio_* function, a thread pool is created, making your process multithreaded if it isn't already. Because of this, after a fork() the child can not use any of the aio_*() functions if the parent used any aio_*() functions before the fork(). The thread pool isn't destroyed until your process ends.