Module Name: src
Committed By: jruoho
Date: Mon May 17 17:15:42 UTC 2010
Modified Files:
src/distrib/sets/lists/comp: mi
src/lib/librt: Makefile
Added Files:
src/lib/librt: aio.3
Log Message:
Add an introductory manual page for the POSIX asynchronous I/O, aio(3).
This is hopefully enough for a reader to get started with the aio.
ok rmind@
To generate a diff of this commit:
cvs rdiff -u -r1.1448 -r1.1449 src/distrib/sets/lists/comp/mi
cvs rdiff -u -r1.10 -r1.11 src/lib/librt/Makefile
cvs rdiff -u -r0 -r1.1 src/lib/librt/aio.3
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/distrib/sets/lists/comp/mi
diff -u src/distrib/sets/lists/comp/mi:1.1448 src/distrib/sets/lists/comp/mi:1.1449
--- src/distrib/sets/lists/comp/mi:1.1448 Mon May 17 07:10:15 2010
+++ src/distrib/sets/lists/comp/mi Mon May 17 17:15:42 2010
@@ -1,4 +1,4 @@
-# $NetBSD: mi,v 1.1448 2010/05/17 07:10:15 jruoho Exp $
+# $NetBSD: mi,v 1.1449 2010/05/17 17:15:42 jruoho Exp $
#
# Note: don't delete entries from here - mark them as "obsolete" instead.
#
@@ -4804,6 +4804,7 @@
./usr/share/man/cat3/addr.0 comp-c-catman .cat
./usr/share/man/cat3/addstr.0 comp-c-catman .cat
./usr/share/man/cat3/affinity.0 comp-c-catman .cat
+./usr/share/man/cat3/aio.0 comp-c-catman .cat
./usr/share/man/cat3/aio_cancel.0 comp-c-catman .cat
./usr/share/man/cat3/aio_error.0 comp-c-catman .cat
./usr/share/man/cat3/aio_fsync.0 comp-c-catman .cat
@@ -10704,6 +10705,7 @@
./usr/share/man/html3/addr.html comp-c-htmlman html
./usr/share/man/html3/addstr.html comp-c-htmlman html
./usr/share/man/html3/affinity.html comp-c-htmlman html
+./usr/share/man/html3/aio.html comp-c-htmlman html
./usr/share/man/html3/aio_cancel.html comp-c-htmlman html
./usr/share/man/html3/aio_error.html comp-c-htmlman html
./usr/share/man/html3/aio_fsync.html comp-c-htmlman html
@@ -16404,6 +16406,7 @@
./usr/share/man/man3/addr.3 comp-c-man .man
./usr/share/man/man3/addstr.3 comp-c-man .man
./usr/share/man/man3/affinity.3 comp-c-man .man
+./usr/share/man/man3/aio.3 comp-c-man .man
./usr/share/man/man3/aio_cancel.3 comp-c-man .man
./usr/share/man/man3/aio_error.3 comp-c-man .man
./usr/share/man/man3/aio_fsync.3 comp-c-man .man
Index: src/lib/librt/Makefile
diff -u src/lib/librt/Makefile:1.10 src/lib/librt/Makefile:1.11
--- src/lib/librt/Makefile:1.10 Mon Jan 5 21:19:48 2009
+++ src/lib/librt/Makefile Mon May 17 17:15:42 2010
@@ -1,4 +1,4 @@
-# $NetBSD: Makefile,v 1.10 2009/01/05 21:19:48 rmind Exp $
+# $NetBSD: Makefile,v 1.11 2010/05/17 17:15:42 jruoho Exp $
#
WARNS= 2
@@ -7,7 +7,7 @@
SRCS= sem.c
SRCS+= pset.c
-MAN+= aio_cancel.3 aio_error.3 aio_fsync.3 aio_read.3 aio_return.3 \
+MAN+= aio.3 aio_cancel.3 aio_error.3 aio_fsync.3 aio_read.3 aio_return.3 \
aio_suspend.3 aio_write.3 lio_listio.3 \
mq_close.3 mq_getattr.3 mq_notify.3 mq_open.3 mq_receive.3 \
mq_send.3 mq_setattr.3 mq_unlink.3 \
Added files:
Index: src/lib/librt/aio.3
diff -u /dev/null src/lib/librt/aio.3:1.1
--- /dev/null Mon May 17 17:15:42 2010
+++ src/lib/librt/aio.3 Mon May 17 17:15:42 2010
@@ -0,0 +1,358 @@
+.\" $NetBSD: aio.3,v 1.1 2010/05/17 17:15:42 jruoho Exp $ $
+.\"
+.\" Copyright (c) 2010 Jukka Ruohonen <jruoho...@iki.fi>
+.\" 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 17, 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 this 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
+.Fa buf ,
+.Fa fildes ,
+and
+.Fa 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.
+Each operation must specify an offset, but the actual file offset
+is never updated as a result of an
+.Nm
+operation.
+.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
+and
+.Xr write 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 structure
+.Em sigevent
+is defined in
+.In signal.h .
+The relevant fields for
+.Nm
+are
+.Va sigev_notify ,
+.Va sigev_signo ,
+and the function pointer
+.Va sigev_notify_function .
+The
+.Va sigev_notify
+member determines the type of the action:
+.Bl -enum -offset indent
+.It
+If it is
+.Dv SIGEV_NONE ,
+no notification is sent.
+.It
+If it is
+.Dv SIGEV_SIGNAL ,
+the signal determined by
+.Va sigev_signo
+is sent when the operation completes.
+.It
+If it is
+.Dv SIGEV_THREAD ,
+a thread is created which starts executing the function specified by
+.Va sigev_notify_function .
+.El
+.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
+.Dq 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
+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.
