aio_reap man page on HP-UX

Man page or keyword search:  
man Server   10987 pages
apropos Keyword Search (all sections)
Output format
HP-UX logo
[printable version]

aio_reap(2)							   aio_reap(2)

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


       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

       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

       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

   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.

       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

       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.

       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

	      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

	      No free memory available.

	      Error copying data from or to the user address space.

	      The	     time has elapsed and less than AIO	 requests  are

	      A signal interrupted the
			     function  and  less  than AIO requests are avail‐

	      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.

       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.

       was developed by HP.

       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),


List of man pages available for HP-UX

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
Vote for polarhome
Free Shell Accounts :: the biggest list on the net