HP-UX Reference (11i v3 07/02) - 2 System Calls (vol 5)

a
aio_reap(2) aio_reap(2)
NAME
aio_reap() - wait for multiple asynchronous I/O requests
SYNOPSIS
#include <sys/lock.h>
typedef struct aio_completion_data {
struct aiocb *aio_aiocb;
int aio_return;
int aio_error;
} aio_completion_t;
int aio_reap(aio_completion_t list[], int nent, const struct timespec
*timeout, int waitfor, int *completed_count);
DESCRIPTION
The aio_reap() function is an extension of the
aio_suspend() library function. Refer to the
aio_suspend()
manpage for a general description of the interface, the aiocb data structure and other
structures relevant for asynchronous I/O (AIO). The
timeout function parameter has the same meaning
as for the aio_suspend() function.
This function suspends the calling thread until at least
waitfor AIO operations scheduled earlier by the
process have completed, until a signal interrupts the function, or, if timeout is not NULL, until the time
interval specified by timeout has passed.
In addition, this function supports a light-weight polling mode. (See below.)
To use aio_reap() , the reap mechanism must be initiated by making a light-weight polling call to
aio_reap() . This call must be made before calling any other AIO functions. (See Usage Notes below)
After this call, the use of
aio_error() , aio_return() , and aio_suspend()
becomes undefined.
In future releases,
aio_cancel() and aio_fsync() may also become undefined. The aio_reap()
mechanism is meant to be as efficient as possible, and is not meant for mixing with these other more costly
features.
Each
aiocb request structure to be returned by this function must have been scheduled earlier by
aio_write() , aio_read() ,orlio_listio() functions.
None of the AIO requests to be reaped may use the lio_listio() asynchronous notification mechan-
ism, or the LIO_WAIT flag. If any of the aiocb structures in the list array were submitted with asyn-
chronous notification or LIO_WAIT, the result is undefined.
The waitfor parameter specifies the number of AIO requests that must be completed before the function
returns to the calling process. The value must be greater than 0 and less than or equal to
nent and
MAX_AIO_REAP , which is defined in aio.h. MAX_AIO_REAP defines the maximum number of AIO
requests that the system is capable of reaping in one invocation of aio_reap() .
The list argument is an array of aio_completion_t
structures, and each element of the array must
be zeroed out before calling
aio_reap() . There must be at least nent number of elements in this
array. For each IO collected by aio_reap(), the fields of an aio_completion_t
in list will be
filled in as follows:
aio_aiocb pointer to the aiocb structure that issued this I/O
aio_return analogous to value obtained from aio_return()
aio_error
analogous to value obtained from aio_error()
(Note that the position of items in this list does not necessarily reflect the order of the members in the
structure.)
The number of AIO requests reaped (and, analogously, the number of aio_completion_t structures
filled in) is returned into the address specified by completed_count.
Use of the aio_reap() interface results in complete processing of each IO, eliminating the need to call
aio_return() or aio_error() for each IO.
The use of aio_reap() in an application should not be mixed with the older aio_return() or
aio_error() functions. Mixing of the two methods of IO collection will result in undefined behavior and
possible data loss.
46 Hewlett-Packard Company − 1 − HP-UX 11i Version 3: February 2007