\" $NetBSD: aio.3,v 1.5 2010/05/19 06:35:20 jruoho Exp $ $
\"
\" Copyright (c) 2010 Jukka Ruohonen <[email protected]>
\" All rights reserved.
\"
\" Redistribution and use in source and binary forms, with or without
\" modification, are permitted provided that the following conditions
\" are met:
\" 1. Redistributions of source code must retain the above copyright
\"    notice, this list of conditions and the following disclaimer.
\" 2. Redistributions in binary form must reproduce the above copyright
\"    notice, this list of conditions and the following disclaimer in the
\"    documentation and/or other materials provided with the distribution.
\"
\" THIS SOFTWARE IS PROVIDED BY Softweyr LLC AND CONTRIBUTORS ``AS IS'' AND
\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
\" ARE DISCLAIMED.  IN NO EVENT SHALL Softweyr LLC OR CONTRIBUTORS BE LIABLE
\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
\" SUCH DAMAGE.
\"
Dd May 19, 2010
Dt AIO 3
Os
Sh NAME
Nm aio
Nd asynchronous I/O (REALTIME)
Sh LIBRARY
Lb librt
Sh SYNOPSIS
In aio.h
Sh DESCRIPTION
The
St -p1003.1-2001
standard defines an interface for asynchronous input and output.
Although in
Nx
this is provided as part of the
Lb librt ,
the implementation largely resides in the kernel.
Ss Rationale
The rationale can be roughly summarized with the following points.
Bl -enum -offset 2n
It
To increase performance by providing a mechanism to carry out
Tn I/O
without blocking.
Theoretically, if
Tn I/O
would never block,
neither at the software nor at the hardware level,
the overhead of
Tn I/O
would become zero, and processes would no longer be
Tn I/O
bound.
It
To segregate the different
Tn I/O
operations into logically distinctive procedures.
Unlike with the standard
Xr stdio 3 ,
the
Nm
interface separates queuing and submitting
Tn I/O
operations to the kernel, and
receiving notifications of operation completion from the kernel.
It
To provide an uniform and standardized framework for asynchronous
Tn I/O .
For instance,
Nm
avoids the need for (and the overhead of) extra worker threads
sometimes used to perform asynchronous
Tn I/O .
El
Ss Asynchronous I/O Control Block
The Asynchronous I/O Control Block is the basic operational unit behind
Nm .
This is required since an arbitrary number of operations can be started
at once, and because each operation can be either input or output.
This block is represented by the
Em aiocb
structure, which is defined in the
In aio.h
header.
The following fields are available for user applications:
Bd -literal -offset indent
off_t            aio_offset;
void            *aio_buf;
size_t           aio_nbytes;
int              aio_fildes;
int              aio_lio_opcode;
int              aio_reqprio;
struct sigevent  aio_sigevent;
Ed
Pp
The fields are:
Bl -enum -offset indent
It
The
Va aio_offset
specifies the implicit file offset at which the
Tn I/O
operations are performed.
This cannot be expected to be the actual read/write offset of the
file descriptor.
It
The
Va aio_buf
member is a pointer to the buffer to which data is going to be written or
to which the read operation stores data.
It
The
Va aio_nbytes
specifies the length of
Va aio_buf .
It
The
Va aio_fildes
specifies the used file descriptor.
It
The
Va aio_lio_opcode
is used by the
Fn lio_listio
function to initialize a list of
Tn I/O
requests with a single call.
It
The
Va aio_reqprio
member can be used to lower the scheduling priority of an
Nm
operation.
This is only available if
Dv _POSIX_PRIORITIZED_IO
and
Dv _POSIX_PRIORITY_SCHEDULING
are defined, and the associated file descriptor supports it.
It
The
Va aio_sigevent
member is used to specify how the calling process is notified once an
Nm
operation completes.
El
Pp
The members
Va aio_buf ,
Va aio_fildes ,
and
Va aio_nbytes
are conceptually similar to the parameters
Sq buf ,
Sq fildes ,
and
Sq nbytes
used in the standard
Xr read 2
and
Xr write 2
functions.
For example, the caller can read
Va aio_nbytes
from a file associated with the file descriptor
Va aio_fildes
into the buffer
Va aio_buf .
All appropriate fields should be initialized by the caller before
Fn aio_read
or
Fn aio_write
is called.
Ss File Offsets
Asynchronous
Tn I/O
operations are not strictly sequential;
operations are carried out in arbitrary order and more than one
operation for one file descriptor can be started.
The requested read or write operation starts
from the absolute position specified by
Va aio_offset ,
as if
Xr lseek 2
would have been called with
Dv SEEK_SET
immediately prior to the operation.
The
Tn POSIX
standard does not specify what happens after an
Nm
operation has been successfully completed.
Depending on the implementation,
the actual file offset may or may not be updated.
Ss Errors and Completion
Asynchronous
Tn I/O
operations are said to be complete when:
Bl -bullet -offset 2n
It
An error is detected.
It
The
Tn I/O
transfer is performed successfully.
It
The operation is canceled.
El
Pp
If an error condition is detected that prevents
an operation from being started, the request is not enqueued.
In this case the read and write functions,
Fn aio_read
and
Fn aio_write ,
return immediately, setting the global
Va errno
to indicate the cause of the error.
Pp
After an operation has been successfully enqueued,
Fn aio_error
and
Fn aio_return
must be used to determine the status of the operation and to determine
any error conditions.
This includes the conditions reported by the standard
Xr read 2 ,
Xr write 2 ,
and
Xr fsync 2 .
The request remains enqueued and consumes process and
system resources until
Fn aio_return
is called.
Ss Waiting for Completion
The
Nm
interface supports both polling and notification models.
The first can be implemented by simply repeatedly calling the
Fn aio_error
function to test the status of an operation.
Once the operation has completed,
Fn aio_return
is used to free the
Va aiocb
structure for re-use.
Pp
The notification model is implemented by using the
Va aio_sigevent
member of the Asynchronous I/O Control Block.
The operational model and the used structure are described in
Xr sigevent 3 .
Pp
The
Fn aio_suspend
function can be used to wait for the completion of one or more operations.
It is possible to set a timeout so that the process can continue the
execution and take recovery actions if the
Nm
operations do not complete as expected.
Ss Cancellation and Synchronization
The
Fn aio_cancel
function can be used to request cancellation of an asynchronous
Tn I/O
operation.
Note however that not all of them can be canceled.
The same
Va aiocb
used to start the operation may be used as a handle for identification.
It is also possible to request cancellation of all operations pending
for a file.
Pp
Comparable to
Xr fsync 2 ,
the
Fn aio_fsync
function can be used to synchronize the contents of
permanent storage when multiple asynchronous
Tn I/O
operations are outstanding for the file or device.
The synchronization operation includes only those requests that have
already been successfully enqueued.
Sh FUNCTIONS
The following functions comprise the
Tn API
of the
Nm
interface:
Bl -column -offset indent "aio_suspend " "XXX"
It Sy Function Ta Sy Description
It Xr aio_cancel 3 Ta cancel an outstanding asynchronous I/O operation
It Xr aio_error 3 Ta retrieve error status of asynchronous I/O operation
It Xr aio_fsync 3 Ta asynchronous data synchronization of file
It Xr aio_read 3 Ta asynchronous read from a file
It Xr aio_return 3 Ta get return status of asynchronous I/O operation
It Xr aio_suspend 3 Ta suspend until operations or timeout complete
It Xr aio_write 3 Ta asynchronous write to a file
It Xr lio_listio 3 Ta list directed I/O
El
Sh COMPATIBILITY
Unfortunately, the
Tn POSIX
asynchronous
Tn I/O
implementations vary slightly.
Some implementations provide a slightly different
Tn API
with possible extensions.
For instance, the
Fx
implementation uses a function
Sq Fn aio_waitcomplete
to wait for the next completion of an
Nm aio
request.
Sh STANDARDS
The
Nm
interface is expected to conform to the
St -p1003.1-2001
standard.
Sh HISTORY
The
Nm
interface first appeared in
Nx 5.0 .
Sh CAVEATS
Few limitations can be mentioned:
Bl -bullet
It
Undefined behavior results if simultaneous asynchronous operations
use the same Asynchronous I/O Control Block.
It
When an asynchronous read operation is outstanding,
undefined behavior may follow if the contents of
Va aiocb
are altered, or if memory associated with the structure, or the
Va aio_buf
buffer, is deallocated.
El

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.