aio_reap.2 (2010 09)

ManualsBrandsHP ManualsSoftwareHP-UX Manpages

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 speciﬁed 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 undeﬁned.

In future releases,

aio_cancel() and aio_fsync() may also become undeﬁned. The aio_reap()

mechanism is meant to be as efﬁcient 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 notiﬁcation mechan-

ism, or the LIO_WAIT ﬂag. If any of the aiocb structures in the list array were submitted with asyn-

chronous notiﬁcation or LIO_WAIT, the result is undeﬁned.

The

waitfor parameter speciﬁes the number of AIO requests that must be completed before the func-

tion 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 deﬁned in aio.h. MAX_AIO_REAP deﬁnes 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 ﬁelds of an aio_completion_t in list will be

ﬁlled 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 reﬂect the order of the members in the

structure.)

The number of AIO requests reaped (and, analogously, the number of

aio_completion_t structures

ﬁlled in) is returned into the address speciﬁed 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 undeﬁned behavior

and possible data loss.

HP-UX 11i Version 3: September 2010 − 1 − Hewlett-Packard Company 1

Summary of content (4 pages)

PAGE 1
aio_reap(2) aio_reap(2) NAME aio_reap() - wait for multiple asynchronous I/O requests SYNOPSIS #include 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, *timeout, int waitfor, int *completed_count); A const struct timespec DESCRIPTION The aio_reap() function is an extension of the aio_suspend() library function.
PAGE 2
aio_reap(2) aio_reap(2) 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()).
PAGE 3
aio_reap(2) aio_reap(2) 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 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.
PAGE 4
(Notes) A (Notes) aA 4 Hewlett-Packard Company −1− HP-UX 11i Version 3: September 2010