aio_reap(2)aio_reap(2)NAMEaio_reap() - wait for multiple asynchronous I/O requests
SYNOPSISDESCRIPTION
The function is an extension of the library function. Refer to the
manpage for a general description of the interface, the data structure
and other structures relevant for asynchronous I/O (AIO). The function
parameter has the same meaning as for the function.
This function suspends the calling thread until at least AIO operations
scheduled earlier by the process have completed, until a signal inter‐
rupts the function, or, if is not NULL, until the time interval speci‐
fied by has passed.
In addition, this function supports a light-weight polling mode. (See
below.)
To use the reap mechanism must be initiated by making a light-weight
polling call to This call must be made before calling any other AIO
functions. (See below) After this call, the use of and becomes unde‐
fined. In future releases, and may also become undefined. The mecha‐
nism is meant to be as efficient as possible, and is not meant for mix‐
ing with these other more costly features.
Each request structure to be returned by this function must have been
scheduled earlier by or functions.
None of the AIO requests to be reaped may use the asynchronous notifi‐
cation mechanism, or the flag. If any of the structures in the list
array were submitted with asynchronous notification or the result is
undefined.
The parameter specifies the number of AIO requests that must be com‐
pleted before the function returns to the calling process. The value
must be greater than and less than or equal to and which is defined in
defines the maximum number of AIO requests that the system is capable
of reaping in one invocation of
The argument is an array of structures, and each element of the array
must be zeroed out before calling There must be at least number of ele‐
ments in this array. For each IO collected by the fields of an in will
be filled in as follows:
pointer to the aiocb structure that issued this I/O
analogous to value obtained from
analogous to value obtained from
(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
structures filled in) is returned into the address specified by
Use of the interface results in complete processing of each IO, elimi‐
nating the need to call or for each IO.
The use of in an application should not be mixed with the older or
functions. Mixing of the two methods of IO collection will result in
undefined behavior and possible data loss.
The parameter must be either NULL or point to a structure that has a
timeout time specified. If a pointer is specified, then no timeout
handling is performed and blocks until AIO requests are available. If
points to a zero-value structure, returns immediately after checking
for any completed AIO requests (behaves similar to
The function call returns to the calling process in any of the follow‐
ing conditions:
1. the specified number of completed requests are available, or
2. the timeout time has elapsed, or
3. a signal has interrupted the function, or
4. an error situation is detected.
In all cases, will attempt to collect as many IOs as possible at the
time of its return, even if less than IOs have completed when a time‐
out, signal, or error interrupts If more than IOs have completed, will
attempt to return up to IOs. As a result, the value of should be
checked after all calls to (regardless of its return value or errno
status).
Light-Weight Polling Mode
When called with all arguments (except for will simply return in the
number of IOs that have completed and are ready for collection.
In light-weight polling mode, is implemented to execute quickly, with‐
out requiring the cost of a regular system call. This allows applica‐
tions to poll for completed IOs without incurring significant costs.
(Note: all releases will provide this polling functionality, but the
actual mechanism by which lightweight polling is implemented is release
specific. However, it should in all cases be faster than a regular
system call.)
Multithreading Notes
The interface is completely thread safe, but there are three issues
that multithreaded applications should be aware of:
The first is starvation. When multiple threads concurrently perform
calls, there is no guarantee that completed I/Os will be distributed
fairly across the calls. For example, if I/Os are issued and two
threads call with and there is no guarantee that both threads will col‐
lect any particular number of I/Os. In fact, one possible outcome is
that the first thread's call to will collect all I/Os, and the second
thread will have none to collect. Multithreaded applications should
take this possibility into consideration, and make appropriate use of
values to prevent unbounded waits in starvation situations.
Another related issue is that when threads perform calls, they can col‐
lect I/Os issued by any thread in the process (not just the calling
thread). As an example, if thread A and thread B each issue 10 I/Os,
and then each calls with and no assumptions can be made about which
I/Os each call to will collect. Thread A's call to might collect all
10 of thread A's I/Os, all 10 of thread B's I/Os, or any mixture of the
two. The only guaranteed behavior is that the first call to will col‐
lect the first 10 I/Os to complete.
The third issue is that it is possible for multiple threads to disrupt
execution of if they corrupt the arguments to during its execution.
For example, problems can arise if one thread of a multithreaded appli‐
cation invalidates the pointer used by another thread concurrently exe‐
cuting a call to (e.g. by freeing or mlocking the corresponding mem‐
ory). If this happens, it is possible for to complete I/Os and fill in
structures but then be unable to update In this case will return with
set to but will have no way to let the application know how many IOs it
has completed. The completed I/Os will be stored in but the applica‐
tion will not be able to know how many I/Os have completed, so it is
possible to lose I/Os in this case. Multithreaded applications must
avoid this situation.
Usage Notes
To use link in the realtime library by specifying on the compiler or
linker command line. Then, before making any AIO function calls, ini‐
tialize the reap mechanism by calling in lightweight mode, as shown in
this example:
For this single call to initialize all output (including return value)
should be ignored.
RETURN VALUE
returns 0 if or more AIO requests have completed. The reaped requests
(the addresses of the completed AIO requests) are copied to the array
and the number of AIO requests reaped is returned into the address
specified by
If the function was interrupted by a signal, the function returns and
is set to If the function was interrupted because the time has elapsed,
the function returns and is set to In either case, actual number of
requests completed at the time of the interrupt is returned in and
these requests are copied to -- even if the number of AIO requests
reaped is less than
If the total number of outstanding AIO requests for that process is
less than will return and set to after all remaining requests have been
reaped. The only exception is if time has elapsed, in which case the
preceding rule applies.
If an error is discovered, the return value is contains additional
information.
In light-weight polling mode, returns 0 and sets to the number of IOs
that are ready for collection. If an irrecoverable error occurs, will
return and leave unchanged.
ERRORS
If returns -1, contains one of the following errors:
is less than or equal to 0, greater than
or greater than the configured maximum possible
number of AIO requests the system can reap in one
call
time is not a valid
is less than or greater than the configured maximum possible
number of AIO requests the system can reap in one
call
No free memory available.
Error copying data from or to the user address space.
The time has elapsed and less than AIO requests are
available.
A signal interrupted the
function and less than AIO requests are avail‐
able.
The system had fewer than
outstanding AIO requests available.
has not been properly initialized. That is, the first AIO func‐
tion called by
this process was not so is not available for use.
APPLICATION USAGE
Note that if returns the caller should check the value of and to deter‐
mine whether any AIO requests have been reaped.
is designed for high performance handling of a large number of out‐
standing AIO requests. It increases the throughput of AIO by reducing
the number of calls to reap AIO requests, and by not hanging up on
individual AIO requests that may be taking a long time to complete.
AUTHOR
was developed by HP.
SEE ALSOaio_cancel(2), aio_error(2), aio_fsync(2), aio_read(2), aio_return(2),
aio_suspend(2), aio_write(2), lio_listio(2), aio(5), aio_iosize_max(5),
aio_proc_max(5).
aio_reap(2)
