Suspends the calling process until a certain number of asynchronous I/O requests are completed.
Standard C Library (libc.a)
#include <aio.h> int aio_nwait (cnt, nwait, list) int cnt; int nwait; struct aiocb **list;
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.
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. |
| cnt | Specifies the number of entries in the list array. |
| nwait | Specifies the minimal number of requests to wait on. |
| list | An array of pointers to aio control structures defined in the aio.h file. |
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:
| 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. |
aio_suspend or aio_suspend64 Subroutine, aio_cancel or aio_cancel64 Subroutine, aio_error or aio_error64 Subroutine, aio_read or aio_read64 Subroutine, aio_return or aio_return64 Subroutine, aio_write or aio_write64 Subroutine, and lio_listio or lio_listio64 Subroutine.
The Asynchronous I/O Overview and the Communications I/O Subsystem: Programming Introduction in AIX 5L Version 5.2 Kernel Extensions and Device Support Programming Concepts.
The Input and Output Handling Programmer's Overview in AIX 5L Version 5.2 General Programming Concepts: Writing and Debugging Programs describes the files, commands, and subroutines used for low-level, stream, terminal, and asynchronous I/O interfaces.