svn commit: r197828 - projects/tcp_ffcaia2008_8.x/share/man/man9
Lawrence Stewart
lstewart at FreeBSD.org
Wed Oct 7 08:43:07 UTC 2009
Author: lstewart
Date: Wed Oct 7 08:43:06 2009
New Revision: 197828
URL: http://svn.freebsd.org/changeset/base/197828
Log:
Update the ALQ(9) man page to discuss the new functionality.
Sponsored by: FreeBSD Foundation
Modified:
projects/tcp_ffcaia2008_8.x/share/man/man9/alq.9
Modified: projects/tcp_ffcaia2008_8.x/share/man/man9/alq.9
==============================================================================
--- projects/tcp_ffcaia2008_8.x/share/man/man9/alq.9 Wed Oct 7 07:04:08 2009 (r197827)
+++ projects/tcp_ffcaia2008_8.x/share/man/man9/alq.9 Wed Oct 7 08:43:06 2009 (r197828)
@@ -1,7 +1,13 @@
.\"
.\" Copyright (c) 2003 Hiten Pandya <hmp at FreeBSD.org>
+.\" Copyright (c) 2009 The FreeBSD Foundation
.\" All rights reserved.
.\"
+.\" Portions of this software were developed at the Centre for Advanced
+.\" Internet Architectures, Swinburne University of Technology, Melbourne,
+.\" Australia by Lawrence Stewart under sponsorship from the FreeBSD
+.\" Foundation.
+.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
@@ -25,16 +31,18 @@
.\"
.\" $FreeBSD$
.\"
-.Dd May 16, 2003
+.Dd October 6, 2009
.Dt ALQ 9
.Os
.Sh NAME
.Nm alq ,
.Nm alq_open ,
.Nm alq_write ,
+.Nm alq_writen ,
.Nm alq_flush ,
.Nm alq_close ,
.Nm alq_get ,
+.Nm alq_getn ,
.Nm alq_post
.Nd Asynchronous Logging Queues
.Sh SYNOPSIS
@@ -49,19 +57,23 @@
.Fa "int count"
.Fc
.Ft int
-.Fn alq_write "struct alq *alq" "void *data" "int waitok"
+.Fn alq_write "struct alq *alq" "void *data" "int flags"
+.Ft int
+.Fn alq_writen "struct alq *alq" "void *data" "int len" "int flags"
.Ft void
.Fn alq_flush "struct alq *alq"
.Ft void
.Fn alq_close "struct alq *alq"
.Ft struct ale *
-.Fn alq_get "struct alq *alq" "int waitok"
+.Fn alq_get "struct alq *alq" "int flags"
+.Ft struct ale *
+.Fn alq_getn "struct alq *alq" "int len" "int flags"
.Ft void
.Fn alq_post "struct alq *alq" "struct ale *ale"
.Sh DESCRIPTION
The
.Nm
-facility provides an asynchronous fixed length recording
+facility provides an asynchronous fixed or variable length recording
mechanism, known as Asynchronous Logging Queues.
It can record to any
.Xr vnode 9 ,
@@ -81,26 +93,37 @@ is defined as
which has the following members:
.Bd -literal -offset indent
struct ale {
- struct ale *ae_next; /* Next Entry */
- char *ae_data; /* Entry buffer */
- int ae_flags; /* Entry flags */
+ intptr_t ae_bytesused; /* # bytes written to ALE. */
+ char *ae_data; /* Write ptr. */
+ int ae_pad; /* Unused, compat. */
};
.Ed
.Pp
-The
-.Va ae_flags
-field is for internal use, clients of the
+An
+.Nm
+can be created in either fixed or variable length mode.
+A variable length
.Nm
-interface should not modify this field.
-Behaviour is undefined if this field is modified.
+accommodates writes of varying length using
+.Fn alq_writen
+and
+.Fn alq_getn .
+A fixed length
+.Nm
+accommodates a fixed number of writes using
+.Fn alq_write
+and
+.Fn alq_get ,
+each of fixed size (set at queue creation time).
+Fixed length mode is deprecated in favour of variable length mode.
.Sh FUNCTIONS
The
.Fn alq_open
-function creates a new logging queue.
+function creates a new asynchronous logging queue.
The
.Fa file
-argument is the name of the file to open for logging; if the file does not
-yet exist,
+argument is the name of the file to open for logging.
+If the file does not yet exist,
.Fn alq_open
will attempt to create it.
The
@@ -115,30 +138,60 @@ a default creation mode suitable for mos
The argument
.Fa cred
specifies the credentials to use when opening and performing I/O on the file.
-The size of each entry in the queue is determined by
-.Fa size .
-The
+To create a variable length mode
+.Nm ,
+the
+.Fa size
+argument should be set to the size (in bytes) of the underlying queue and the
+.Fa count
+argument should be set to 0.
+To create a fixed length mode
+.Nm ,
+the
+.Fa size
+argument should be set to the size (in bytes) of each write and the
.Fa count
-argument determines the number of items to be stored in the
-asynchronous queue over an approximate period of a disk
-write operation.
+argument should be set to the number of
+.Fa size
+byte chunks to reserve capacity for.
.Pp
The
-.Fn alq_write
+.Fn alq_writen
function writes
+.Fa len
+bytes from
.Fa data
-to the designated queue,
+to the designated variable length mode queue
.Fa alq .
-In the event that
-.Fn alq_write
-could not write the entry immediately, and
+If
+.Fn alq_writen
+could not write the entry immediately and
.Dv ALQ_WAITOK
-is passed to
-.Fa waitok ,
-then
+is set in
+.Fa flags ,
+the function will be allowed to
+.Xr msleep_spin 9
+with the
+.Dq Li alqwriten
+wait message.
+.Pp
+The
.Fn alq_write
-will be allowed to
-.Xr tsleep 9 .
+function is implemented as a wrapper around
+.Fn alq_writen
+to provide backwards compatibility to consumers that have not been updated to
+utilise variable length mode queues.
+The function will write
+.Fa size
+bytes of data (where
+.Fa size
+was specified at queue creation time) from the
+.Fa data
+buffer to the
+.Fa alq .
+Note that it is an error to call
+.Fn alq_write
+on a variable length mode queue.
.Pp
The
.Fn alq_flush
@@ -146,61 +199,112 @@ function is used for flushing
.Fa alq
to the log medium that was passed to
.Fn alq_open .
+If
+.Fa alq
+has data to flush and is not already in the process of being flushed, the
+function will block doing IO.
+Otherwise, the function will return immediately.
.Pp
The
.Fn alq_close
-function will close the asynchronous logging queue,
+function will close the asynchronous logging queue
.Fa alq ,
and flush all pending write requests to the log medium.
It will free all resources that were previously allocated.
.Pp
The
-.Fn alq_get
-function returns the next available asynchronous logging entry
-from the queue,
-.Fa alq .
-This function leaves the queue in a locked state, until a subsequent
+.Fn alq_getn
+function returns an asynchronous log entry from
+.Fa alq ,
+initialised to point at a buffer capable of receiving
+.Fa len
+bytes of data.
+This function leaves
+.Fa alq
+in a locked state, until a subsequent
.Fn alq_post
call is made.
-In the event that
-.Fn alq_get
-could not retrieve an entry immediately, it will
-.Xr tsleep 9
+If
+.Fn alq_getn
+could not obtain
+.Fa len
+bytes of buffer immediately and
+.Dv ALQ_WAITOK
+is set in
+.Fa flags ,
+the function will be allowed to
+.Xr msleep_spin 9
with the
-.Dq Li alqget
+.Dq Li alqgetn
wait message.
+The caller can choose to write less than
+.Fa len
+bytes of data to the returned asynchronous log entry by setting the entry's
+ae_bytesused field to the number of bytes actually written.
+This must be done prior to calling
+.Fn alq_post .
.Pp
The
-.Fn alq_post
-function schedules the asynchronous logging entry,
-.Fa ale ,
-which is retrieved using the
.Fn alq_get
-function,
-for writing to the asynchronous logging queue,
+function is implemented as a wrapper around
+.Fn alq_getn
+to provide backwards compatibility to consumers that have not been updated to
+utilise variable length mode queues.
+The asynchronous log entry returned will be initialised to point at a buffer
+capable of receiving
+.Fa size
+bytes of data (where
+.Fa size
+was specified at queue creation time).
+Note that it is an error to call
+.Fn alq_get
+on a variable length mode queue.
+.Pp
+The
+.Fn alq_post
+function schedules the asynchronous log entry
+.Fa ale
+(obtained from
+.Fn alq_getn
+or
+.Fn alq_get )
+for writing to
.Fa alq .
-This function leaves the queue,
+This function leaves
.Fa alq ,
in an unlocked state.
.Sh IMPLEMENTATION NOTES
The
+.Fn alq_writen
+and
.Fn alq_write
-function is a wrapper around the
+functions both perform a
+.Xr bcopy 3
+from the supplied
+.Fa data
+buffer into the underlying
+.Nm
+buffer.
+Performance critical code paths may wish to consider using
+.Fn alq_getn
+(variable length queues) or
+.Fn alq_get
+(fixed length queues) to avoid the extra memory copy. Note that a queue
+remains locked between calls to
+.Fn alq_getn
+or
.Fn alq_get
and
-.Fn alq_post
-functions; by using these functions separately, a call
-to
-.Fn bcopy
-can be avoided for performance critical code paths.
+.Fn alq_post ,
+so this method of writing to a queue is unsuitable for situations where the
+time between calls may be substantial.
.Sh LOCKING
-Each asynchronous queue is protected by a spin mutex.
+Each asynchronous logging queue is protected by a spin mutex.
.Pp
Functions
-.Fn alq_flush ,
-.Fn alq_open
+.Fn alq_flush
and
-.Fn alq_post
+.Fn alq_open
may attempt to acquire an internal sleep mutex, and should
consequently not be used in contexts where sleeping is
not allowed.
@@ -214,32 +318,36 @@ if it fails to open
or else it returns 0.
.Pp
The
+.Fn alq_writen
+and
.Fn alq_write
-function returns
+functions return
.Er EWOULDBLOCK
if
.Dv ALQ_NOWAIT
-was provided as a value to
-.Fa waitok
-and either the queue is full, or when the system is shutting down.
+was set in
+.Fa flags
+and either the queue is full or the system is shutting down.
.Pp
The
+.Fn alq_getn
+and
.Fn alq_get
-function returns
-.Dv NULL ,
+functions return
+.Dv NULL
if
.Dv ALQ_NOWAIT
-was provided as a value to
-.Fa waitok
-and either the queue is full, or when the system is shutting down.
+was set in
+.Fa flags
+and either the queue is full or the system is shutting down.
.Pp
NOTE: invalid arguments to non-void functions will result in
undefined behaviour.
.Sh SEE ALSO
-.Xr syslog 3 ,
-.Xr kthread 9 ,
+.Xr kproc 9 ,
.Xr ktr 9 ,
-.Xr tsleep 9 ,
+.Xr msleep_spin 9 ,
+.Xr syslog 3 ,
.Xr vnode 9
.Sh HISTORY
The
@@ -250,7 +358,11 @@ Asynchronous Logging Queues (ALQ) facili
The
.Nm
facility was written by
-.An Jeffrey Roberson Aq jeff at FreeBSD.org .
+.An Jeffrey Roberson Aq jeff at FreeBSD.org
+and extended by
+.An Lawrence Stewart Aq lstewart at freebsd.org .
.Pp
This manual page was written by
-.An Hiten Pandya Aq hmp at FreeBSD.org .
+.An Hiten Pandya Aq hmp at FreeBSD.org
+and revised by
+.An Lawrence Stewart Aq lstewart at freebsd.org .
More information about the svn-src-projects
mailing list