.TH aio_suspend 3 2002-09-12 "Linux 2.4" Linux AIO"
.SH NAME
aio_suspend \- Wait until one or more requests of a specific set terminates.
.SH SYNOPSYS
.nf
.B "#include <errno.h>"
.sp
.br 
.B "#include <aio.h>"
.sp
.br
.BI "int aio_suspend (const struct aiocb *const list[], int nent, const struct timespec *timeout)"
.fi
.SH DESCRIPTION
Another method of synchronization is to wait until one or more requests of a
specific set terminated.  This could be achieved by the 
.IR "aio_*"
functions to notify the initiating process about the termination but in
some situations this is not the ideal solution.  In a program which
constantly updates clients somehow connected to the server it is not
always the best solution to go round robin since some connections might
be slow.  On the other hand letting the 
.IR "aio_*"
function notify the
caller might also be not the best solution since whenever the process
works on preparing data for on client it makes no sense to be
interrupted by a notification since the new client will not be handled
before the current client is served.  For situations like this
.IR "aio_suspend"
should be used.
.PP
When calling this function, the calling thread is suspended until at
least one of the requests pointed to by the 
.IR "nent"
elements of the
array 
.IR "list"
has completed.  If any of the requests has already
completed at the time 
.IR "aio_suspend"
is called, the function returns
immediately.  Whether a request has terminated or not is determined by
comparing the error status of the request with 
.IR "EINPROGRESS"
.  If
an element of 
.IR "list"
is 
.IR "NULL"
, the entry is simply ignored.

If no request has finished, the calling process is suspended.  If
.IR "timeout"
is 
.IR "NULL"
, the process is not woken until a request
has finished.  If 
.IR "timeout"
is not 
.IR "NULL"
, the process remains
suspended at least as long as specified in 
.IR "timeout"
.  In this case,
.IR "aio_suspend"
returns with an error.
.PP
When the sources are compiled with 
.IR "_FILE_OFFSET_BITS == 64"
this
function is in fact 
.IR "aio_suspend64"
since the LFS interface
transparently replaces the normal implementation.
.SH "RETURN VALUES"
The return value of the function is 
.IR 0
if one or more requests
from the 
.IR "list"
have terminated.  Otherwise the function returns
.IR -1
and 
.IR "errno"
is set.
.SH ERRORS
.TP
.B EAGAIN
None of the requests from the 
.IR "list"
completed in the time specified
by 
.IR "timeout"
.
.TP
.B EINTR
A signal interrupted the 
.IR "aio_suspend"
function.  This signal might
also be sent by the AIO implementation while signalling the termination
of one of the requests.
.TP
.B ENOSYS
The 
.IR "aio_suspend"
function is not implemented.
.SH "SEE ALSO"
.BR aio(3),
.BR aio_cancel(3),
.BR aio_cancel64(3),
.BR aio_error(3),
.BR aio_error64(3),
.BR aio_fsync(3),
.BR aio_fsync64(3),
.BR aio_init(3),
.BR aio_read(3),
.BR aio_read64(3),
.BR aio_return(3),
.BR aio_return64(3),
.BR aio_suspend64(3),
.BR aio_write(3),
.BR aio_write64(3),
.BR errno(3),