Source-Changes-HG archive
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index][Old Index]
[src/trunk]: src Add an introductory manual page for the POSIX asynchronous I...
details: https://anonhg.NetBSD.org/src/rev/6b5212d1be27
branches: trunk
changeset: 754952:6b5212d1be27
user: jruoho <jruoho%NetBSD.org@localhost>
date: Mon May 17 17:15:42 2010 +0000
description:
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@
diffstat:
distrib/sets/lists/comp/mi | 5 +-
lib/librt/Makefile | 4 +-
lib/librt/aio.3 | 358 +++++++++++++++++++++++++++++++++++++++++++++
3 files changed, 364 insertions(+), 3 deletions(-)
diffs (truncated from 413 to 300 lines):
diff -r b0019c54f590 -r 6b5212d1be27 distrib/sets/lists/comp/mi
--- a/distrib/sets/lists/comp/mi Mon May 17 17:01:16 2010 +0000
+++ b/distrib/sets/lists/comp/mi Mon May 17 17:15:42 2010 +0000
@@ -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
diff -r b0019c54f590 -r 6b5212d1be27 lib/librt/Makefile
--- a/lib/librt/Makefile Mon May 17 17:01:16 2010 +0000
+++ b/lib/librt/Makefile Mon May 17 17:15:42 2010 +0000
@@ -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 \
diff -r b0019c54f590 -r 6b5212d1be27 lib/librt/aio.3
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/lib/librt/aio.3 Mon May 17 17:15:42 2010 +0000
@@ -0,0 +1,358 @@
+.\" $NetBSD: aio.3,v 1.1 2010/05/17 17:15:42 jruoho Exp $ $
+.\"
+.\" Copyright (c) 2010 Jukka Ruohonen <jruohonen%iki.fi@localhost>
+.\" 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.
Home |
Main Index |
Thread Index |
Old Index