Copyright (c) 2003 Hiten Pandya <hmp@FreeBSD.org>
Copyright (c) 2009-2010 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:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions, and the following disclaimer,
without modification, immediately at the beginning of the file.
2. The name of the author may not be used to endorse or promote products
derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE AUTHOR 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 THE AUTHOR 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.
$FreeBSD: releng/10.2/share/man/man9/alq.9 207223 2010-04-26 13:48:22Z lstewart $
.Dd April 26, 2010 .Dt ALQ 9 .Os .Sh NAME .Nm alq , .Nm alq_open_flags , .Nm alq_open , .Nm alq_writen , .Nm alq_write , .Nm alq_flush , .Nm alq_close , .Nm alq_getn , .Nm alq_get , .Nm alq_post_flags , .Nm alq_post .Nd Asynchronous Logging Queues .Sh SYNOPSIS n sys/alq.h .Ft int .Fo alq_open_flags .Fa "struct alq **app" .Fa "const char *file" .Fa "struct ucred *cred" .Fa "int cmode" .Fa "int size" .Fa "int flags" .Fc .Ft int .Fo alq_open .Fa "struct alq **app" .Fa "const char *file" .Fa "struct ucred *cred" .Fa "int cmode" .Fa "int size" .Fa "int count" .Fc .Ft int .Fn alq_writen "struct alq *alq" "void *data" "int len" "int flags" .Ft int .Fn alq_write "struct alq *alq" "void *data" "int flags" .Ft void .Fn alq_flush "struct alq *alq" .Ft void .Fn alq_close "struct alq *alq" .Ft struct ale * .Fn alq_getn "struct alq *alq" "int len" "int flags" .Ft struct ale * .Fn alq_get "struct alq *alq" "int flags" .Ft void .Fn alq_post_flags "struct alq *alq" "struct ale *ale" "int flags" .Ft void .Fn alq_post "struct alq *alq" "struct ale *ale" .Sh DESCRIPTION The .Nm facility provides an asynchronous fixed or variable length recording mechanism, known as Asynchronous Logging Queues. It can record to any .Xr vnode 9 , thus providing the ability to journal logs to character devices as well as regular files. All functions accept a .Vt "struct alq" argument, which is an opaque type that maintains state information for an Asynchronous Logging Queue. The logging facility runs in a separate kernel thread, which services all log entry requests.
p An .Dq asynchronous log entry is defined as .Vt "struct ale" , which has the following members: d -literal -offset indent struct ale { intptr_t ae_bytesused; /* # bytes written to ALE. */ char *ae_data; /* Write ptr. */ int ae_pad; /* Unused, compat. */ }; .Ed
p An .Nm can be created in either fixed or variable length mode. A variable length .Nm 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_flags function creates a new variable length asynchronous logging queue. The .Fa file 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 .Fa cmode argument will be passed to .Fn vn_open as the requested creation mode, to be used if the file will be created by .Fn alq_open . Consumers of this API may wish to pass .Dv ALQ_DEFAULT_CMODE , a default creation mode suitable for most applications. The .Fa cred argument specifies the credentials to use when opening and performing I/O on the file. The .Fa size argument sets the size (in bytes) of the underlying queue. The ALQ_ORDERED flag may be passed in via .Fa flags to indicate that the ordering of writer threads waiting for a busy .Nm to free up resources should be preserved.
p The deprecated .Fn alq_open function is implemented as a wrapper around .Fn alq_open_flags to provide backwards compatibility to consumers that have not been updated to utilise the newer .Fn alq_open_flags function. It passes all arguments through to .Fn alq_open_flags untouched except for .Fa size and .Fa count , and sets .Fa flags to 0. 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 should be set to the number of .Fa size byte chunks to reserve capacity for.
p The .Fn alq_writen function writes .Fa len bytes from .Fa data to the designated variable length mode queue .Fa alq . If .Fn alq_writen could not write the entry immediately and .Dv ALQ_WAITOK is set in .Fa flags , the function will be allowed to .Xr msleep_spin 9 with the .Dq Li alqwnord or .Dq Li alqwnres wait message. A write will automatically schedule the queue .Fa alq to be flushed to disk. This behaviour can be controlled by passing ALQ_NOACTIVATE via .Fa flags to indicate that the write should not schedule .Fa alq to be flushed to disk.
p The deprecated .Fn alq_write 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.
p The .Fn alq_flush 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.
p The .Fn alq_close 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.
p The .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 or .Fn alq_post_flags call is made. 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 alqgnord or .Dq Li alqgnres 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 .
p The deprecated .Fn alq_get 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.
p The .Fn alq_post_flags function schedules the asynchronous log entry .Fa ale (obtained from .Fn alq_getn or .Fn alq_get ) for writing to .Fa alq . The ALQ_NOACTIVATE flag may be passed in via .Fa flags to indicate that the queue should not be immediately scheduled to be flushed to disk. This function leaves .Fa alq in an unlocked state.
p The .Fn alq_post function is implemented as a wrapper around .Fn alq_post_flags to provide backwards compatibility to consumers that have not been updated to utilise the newer .Fn alq_post_flags function. It simply passes all arguments through to .Fn alq_post_flags untouched, and sets .Fa flags to 0. .Sh IMPLEMENTATION NOTES The .Fn alq_writen and .Fn alq_write 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 or .Fn alq_post_flags , so this method of writing to a queue is unsuitable for situations where the time between calls may be substantial. .Sh LOCKING Each asynchronous logging queue is protected by a spin mutex.
p Functions .Fn alq_flush and .Fn alq_open may attempt to acquire an internal sleep mutex, and should consequently not be used in contexts where sleeping is not allowed. .Sh RETURN VALUES The .Fn alq_open function returns one of the error codes listed in .Xr open 2 , if it fails to open .Fa file , or else it returns 0.
p The .Fn alq_writen and .Fn alq_write functions return .Er EWOULDBLOCK if .Dv ALQ_NOWAIT was set in .Fa flags and either the queue is full or the system is shutting down.
p The .Fn alq_getn and .Fn alq_get functions return .Dv NULL if .Dv ALQ_NOWAIT was set in .Fa flags and either the queue is full or the system is shutting down.
p NOTE: invalid arguments to non-void functions will result in undefined behaviour. .Sh SEE ALSO .Xr kproc 9 , .Xr ktr 9 , .Xr msleep_spin 9 , .Xr syslog 3 , .Xr vnode 9 .Sh HISTORY The Asynchronous Logging Queues (ALQ) facility first appeared in .Fx 5.0 . .Sh AUTHORS .An -nosplit The .Nm facility was written by .An Jeffrey Roberson Aq jeff@FreeBSD.org and extended by .An Lawrence Stewart Aq lstewart@freebsd.org .
p This manual page was written by .An Hiten Pandya Aq hmp@FreeBSD.org and revised by .An Lawrence Stewart Aq lstewart@freebsd.org .