aio_nwait Subroutine

Purpose

Suspends the calling process until a certain number of asynchronous I/O requests are completed.

Library

Standard C Library (libc.a)

Syntax

#include <aio.h>

int aio_nwait (cnt, nwait, list)
int cnt;
int nwait;
struct aiocb **list;

Description

Although the aio_nwait subroutine is included with POSIX AIO, it is not part of the standard definitions for POSIX AIO.

The aio_nwait subroutine suspends the calling process until a certain number (nwait) of asynchronous I/O requests are completed. These requests are initiated at an earlier time by the lio_listio subroutine, which uses the LIO_NOWAIT_AIOWAIT cmd parameter. The aio_nwait subroutine fills in the aiocb pointers to the completed requests in list and returns the number of valid entries in list. The cnt parameter is the maximum number of aiocb pointers that list can hold (cnt >= nwait). The subroutine also returns when less than nwait number of requests are done if there are no more pending aio requests.

Note: If the lio_listio64 subroutine is used, the aiocb structure changes to aiocb64.

Note: The aio control block's errno field continues to have the value EINPROG until after the aio_nwait subroutine is completed. The aio_nwait subroutine updates this field when the lio_listio subroutine has run with the LIO_NOWAIT_AIOWAIT cmd parameter. No utility, such as aio_error, can be used to look at this value until after the aio_nwait subroutine is completed.

The aio_suspend subroutine returns after any one of the specified requests gets done. The aio_nwait subroutine returns after a certain number (nwait or more) of requests are completed.

There are certain limitations associated with the aio_nwait subroutine, and a comparison between it and the aio_suspend subroutine is necessary. The following table is a comparison of the two subroutines:

aio_suspend:	aio_nwait:
Requires users to build a list of control blocks, each associated with an I/O operation they want to wait for.	Requires the user to provide an array to put aiocb address information into. No specific aio control blocks need to be known.
Returns when any one of the specified control blocks indicates that the I/O associated with that control block completed.	Returns when nwait amount of requests are done or no other requests are to be processed.
The aio control blocks may be updated before the subroutine is called. Other polling methods (such as the aio_error subroutine) can also be used to view the aio control blocks.	Updates the aio control blocks itself when it is called. Other polling methods can't be used until after the aio_nwait subroutine is called enough times to cover all of the aio requests specified with the lio_listio subroutine.
	Is only used in accordance with the LIO_NOWAIT_AIOWAIT command, which is one of the commands associated with the lio_listio subroutine. If the lio_listio subroutine is not first used with the LIO_NOWAIT_AIOWAIT command, aio_nwait can not be called. The aio_nwait subroutine only affects those requests called by one or more lio_listio calls for a specified process.

Parameters

Item	Description
cnt	Specifies the number of entries in the list array. This number must be greater than 0 and less than 64 000.
nwait	Specifies the minimal number of requests to wait on. This number must be greater than 0 and less than or equal to the value specified by the cnt parameter.
list	An array of pointers to aio control structures defined in the aio.h file.

Return Values

The return value is the total number of requests the aio_nwait subroutine has waited on to complete. It can not be more than cnt. Although nwait is the desired amount of requests to find, the actual amount returned could be less than, equal to, or greater than nwait. The return value indicates how much of the list array to access.

The return value may be greater than the nwait value if the lio_listio subroutine initiated more than nwait requests and the cnt variable is larger than nwait. The nwait parameter represents a minimal value desired for the return value, and cnt is the maximum value possible for the return.

The return value may be less than the nwait value if some of the requests initiated by the lio_listio subroutine occur at a time of high activity, and there is a lack of resources available for the number of requests. EAGAIN (error try again later) may be returned in some request's aio control blocks, but these requests will not be seen by the aio_nwait subroutine. In this situation aiocb addresses not found on the list have to be accessed by using the aio_error subroutine after the aio_nwait subroutine is called. You may need to increase the aio parameters max servers or max requests if this occurs. Increasing the parameters will ensure that the system is well tuned, and an EAGAIN error is less likely to occur.

In the event of an error, the aio_nwait subroutine returns a value of -1 and sets the errno global variable to identify the error. Return codes can be set to the following errno values:

Item	Description
EBUSY	An aio_nwait call is in process.
EINVAL	The application has retrieved all of the aiocb pointers, but the user buffer does not have enough space for them.
EINVAL	There are no outstanding async I/O calls.
EINVAL	Specifies cnt or nwait values that are not valid.