Date: Wed, 7 Oct 2009 08:43:07 +0000 (UTC) From: Lawrence Stewart <lstewart@FreeBSD.org> To: src-committers@freebsd.org, svn-src-projects@freebsd.org Subject: svn commit: r197828 - projects/tcp_ffcaia2008_8.x/share/man/man9 Message-ID: <200910070843.n978h7Wl078882@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
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@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@FreeBSD.org . +.An Jeffrey Roberson Aq jeff@FreeBSD.org +and extended by +.An Lawrence Stewart Aq lstewart@freebsd.org . .Pp This manual page was written by -.An Hiten Pandya Aq hmp@FreeBSD.org . +.An Hiten Pandya Aq hmp@FreeBSD.org +and revised by +.An Lawrence Stewart Aq lstewart@freebsd.org .
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?200910070843.n978h7Wl078882>