*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->HP-UX 11i man pages -> aio_reap (2)              


 aio_reap(2)                                                     aio_reap(2)

 NAME    [Toc]    [Back]
      aio_reap() - wait for multiple asynchronous I/O requests

 SYNOPSIS    [Toc]    [Back]
      #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    [Toc]    [Back]
      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

      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(), or lio_listio()

      None of the AIO requests to be reaped may use the lio_listio()
      asynchronous notification mechanism, or the LIO_WAIT flag.  If any of
      the aiocb structures in the list array were submitted with
      asynchronous 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

 Hewlett-Packard Company            - 1 -   HP-UX 11i Version 2: August 2003

 aio_reap(2)                                                     aio_reap(2)

      MAX_IO_REAP, which is defined in aio.h.  MAX_IO_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

      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.

      The timeout parameter must be either NULL or point to a timespec
      structure that has a timeout time specified.  If a NULL pointer is
      specified, then no timeout handling is performed and aio_reap() blocks
      until waitfor AIO requests are available.  If timeout points to a
      zero-value timespec structure, aio_reap() returns immediately after
      checking for any completed AIO requests (behaves similar to poll()).

      The aio_reap() 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.

 Hewlett-Packard Company            - 2 -   HP-UX 11i Version 2: August 2003

 aio_reap(2)                                                     aio_reap(2)

      In all cases, aio_reap() will attempt to collect as many IOs as
      possible at the time of its return, even if less than waitfor IOs have
      completed when a timeout, signal, or error interrupts aio_reap().  If
      more than waitfor IOs have completed, aio_reap() will attempt to
      return up to nent IOs.  As a result, the value of completed_count
      should be checked after all calls to aio_reap() (regardless of its
      return value or errno status).

    Light-Weight Polling Mode    [Toc]    [Back]
      When called with all NULL arguments (except for completed_count),
      aio_reap will simply return in completed_count the number of IOs that
      have completed and are ready for collection.

      In light-weight polling mode, aio_reap() is implemented to execute
      quickly, without requiring the cost of a regular system call.  This
      allows applications 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    [Toc]    [Back]
      The aio_reap() 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
      aio_reap() calls, there is no guarantee that completed I/Os will be
      distributed fairly across the calls.  For example, if 50 I/Os are
      issued and two threads call aio_reap() with waitfor=25 and nent=50,
      there is no guarantee that both threads will collect any particular
      number of I/Os.  In fact, one possible outcome is that the first
      thread's call to aio_reap() will collect all 50 I/Os, and the second
      thread will have none to collect.  Multithreaded applications should
      take this possibility into consideration, and make appropriate use of
      timeout values to prevent unbounded waits in starvation situations.

      Another related issue is that when threads perform aio_reap() 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 aio_reap() with waitfor=10 and
      nent=10, no assumptions can be made about which I/Os each call to
      aio_reap() will collect.  Thread A's call to aio_reap() 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
      aio_reap() will collect the first 10 I/Os to complete.

      The third issue is that it is possible for multiple threads to disrupt
      execution of aio_reap() if they corrupt the arguments to aio_reap()
      during its execution.  For example, problems can arise if one thread

 Hewlett-Packard Company            - 3 -   HP-UX 11i Version 2: August 2003

 aio_reap(2)                                                     aio_reap(2)

      of a multithreaded application invalidates the completed_count pointer
      used by another thread concurrently executing a call to aio_reap()
      (e.g. by freeing or mlocking the corresponding memory).  If this
      happens, it is possible for aio_reap() to complete I/Os and fill in
      aio_completion_t structures but then be unable to update
      completed_count.  In this case aio_reap() will return with errno set
      to [EFAULT], but will have no way to let the application know how many
      IOs it has completed.  The completed I/Os will be stored in list, 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    [Toc]    [Back]
      To use aio_reap(), link in the realtime library by specifying -lrt on
      the compiler or linker command line.  Then, before making any AIO
      function calls, initialize the reap mechanism by calling aio_reap() in
      lightweight mode, as shown in this example:

                int ignore;

                (void)aio_reap(NULL, 0, NULL, 0, &ignore);

      For this single call to initialize aio_reap(), all output (including
      return value) should be ignored.

 RETURN VALUE    [Toc]    [Back]
      aio_reap() returns 0 if waitfor or more AIO requests have completed.
      The reaped requests (the aiocb addresses of the completed AIO
      requests) are copied to the array list, and the number of AIO requests
      reaped is returned into the address specified by completed_count.

      If the function was interrupted by a signal, the function returns -1
      and errno is set to [EINTR].  If the function was interrupted because
      the timeout time has elapsed, the function returns -1 and errno is set
      to [EAGAIN].  In either case, actual number of requests completed at
      the time of the interrupt is returned in completed_count, and these
      requests are copied to list -- even if the number of AIO requests
      reaped is less than waitfor.

      If the total number of outstanding AIO requests for that process is
      less than waitfor, aio_reap() will return -1 and set errno to [E2BIG]
      after all remaining requests have been reaped.  The only exception is
      if timeout time has elapsed, in which case the preceding rule applies.

      If an error is discovered, the return value is -1.  errno contains
      additional information.

      In light-weight polling mode, aio_reap returns 0 and sets
      completed_count to the number of IOs that are ready for collection.
      If an irrecoverable error occurs, aio_reap will return -1 and leave
      completed_count unchanged.

 Hewlett-Packard Company            - 4 -   HP-UX 11i Version 2: August 2003

 aio_reap(2)                                                     aio_reap(2)

 ERRORS    [Toc]    [Back]
      If aio_reap() returns -1, errno contains one of the following errors:

           [EINVAL]       waitfor is less than or equal to 0, greater than
                          nent, or greater than the configured maximum
                          possible number of AIO requests the system can
                          reap in one call MAX_AIO_REAP).

           [EINVAL]       timeout time is not a valid timespec.

           [EINVAL]       nent is less than waitfor or greater than the
                          configured maximum possible number of AIO requests
                          the system can reap in one call MAX_AIO_REAP).

           [ENOMEM]       No free memory available.

           [EFAULT]       Error copying data from or to the user address

           [EAGAIN]       The timeout time has elapsed and less than waitfor
                          AIO requests are available.

           [EINTR]        A signal interrupted the aio_reap() function and
                          less than waitfor AIO requests are available.

           [E2BIG]        The system had fewer than waitfor outstanding AIO
                          requests available.

           [ENOSYS]       The aio_reap() function is not supported by this

 APPLICATION USAGE    [Toc]    [Back]
      Note that if aio_reap() returns -1, the caller should check the value
      of errno and completed_count to determine whether any AIO requests
      have been reaped.

      aio_reap() 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

 AUTHOR    [Toc]    [Back]
      aio_reap() was developed by HP.

 SEE ALSO    [Toc]    [Back]
      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).

 Hewlett-Packard Company            - 5 -   HP-UX 11i Version 2: August 2003
[ Back ]
 Similar pages
Name OS Title
lio_listio Tru64 Initiates a list of asynchronous I/O requests
aio_suspend IRIX wait for an asynchronous I/O request
aio_cancel Tru64 Cancels one or more asynchronous I/O requests pending against the specified file descriptor (P1003.1...
aio_suspend HP-UX wait for an asynchronous I/O operation to complete
glfinishasyncsgix IRIX wait for completion of an asynchronous command
vwaitforio OpenBSD wait for all outstanding asynchronous writes
cprodm1d IRIX Compute the product of Multiple 1D Fourier transforms with Multiple 1D filters.
sprodm1du IRIX Compute the product of Multiple 1D Fourier transforms with Multiple 1D filters.
accept IRIX allow or prevent LP requests
vtdaemon HP-UX respond to vt requests
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service