hpux man page for aio_reap

aio_reap(2)							System Calls Manual						       aio_reap(2)

NAME
       aio_reap() - wait for multiple asynchronous I/O requests

SYNOPSIS

DESCRIPTION
       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
       interrupts the function, or, if is not NULL, until the time interval specified 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 undefined.  In future releases, and may also become undefined.	The mecha-
       nism is meant to be as efficient as possible, and is not meant for mixing 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 notification 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 completed 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 capa-
       ble 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
       elements 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, eliminating 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 following 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, without 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 collect 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 collect 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 application invalidates the pointer used by  another  thread  concurrently
       executing  a call to (e.g. by freeing or mlocking the corresponding memory).  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 application 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 available.

	      The system had fewer than
			     outstanding AIO requests available.

	      has not been properly initialized.  That is, the first AIO function 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 determine whether any AIO requests have been reaped.

       is designed for high performance handling of a large number of outstanding 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 ALSO
       aio_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)