2 .\" Copyright (c) 2003 Hiten Pandya <hmp@FreeBSD.org>
3 .\" Copyright (c) 2009-2010 The FreeBSD Foundation
4 .\" All rights reserved.
6 .\" Portions of this software were developed at the Centre for Advanced
7 .\" Internet Architectures, Swinburne University of Technology, Melbourne,
8 .\" Australia by Lawrence Stewart under sponsorship from the FreeBSD
11 .\" Redistribution and use in source and binary forms, with or without
12 .\" modification, are permitted provided that the following conditions
14 .\" 1. Redistributions of source code must retain the above copyright
15 .\" notice, this list of conditions, and the following disclaimer,
16 .\" without modification, immediately at the beginning of the file.
17 .\" 2. The name of the author may not be used to endorse or promote products
18 .\" derived from this software without specific prior written permission.
20 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR
24 .\" ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
49 .Nd Asynchronous Logging Queues
54 .Fa "struct alq **app"
55 .Fa "const char *file"
56 .Fa "struct ucred *cred"
63 .Fa "struct alq **app"
64 .Fa "const char *file"
65 .Fa "struct ucred *cred"
71 .Fn alq_writen "struct alq *alq" "void *data" "int len" "int flags"
73 .Fn alq_write "struct alq *alq" "void *data" "int flags"
75 .Fn alq_flush "struct alq *alq"
77 .Fn alq_close "struct alq *alq"
79 .Fn alq_getn "struct alq *alq" "int len" "int flags"
81 .Fn alq_get "struct alq *alq" "int flags"
83 .Fn alq_post_flags "struct alq *alq" "struct ale *ale" "int flags"
85 .Fn alq_post "struct alq *alq" "struct ale *ale"
89 facility provides an asynchronous fixed or variable length recording
90 mechanism, known as Asynchronous Logging Queues.
93 thus providing the ability to journal logs to character
94 devices as well as regular files.
95 All functions accept a
97 argument, which is an opaque type that maintains state information
98 for an Asynchronous Logging Queue.
99 The logging facility runs in a separate kernel thread, which services
100 all log entry requests.
103 .Dq asynchronous log entry
106 which has the following members:
107 .Bd -literal -offset indent
109 intptr_t ae_bytesused; /* # bytes written to ALE. */
110 char *ae_data; /* Write ptr. */
111 int ae_pad; /* Unused, compat. */
117 can be created in either fixed or variable length mode.
120 accommodates writes of varying length using
126 accommodates a fixed number of writes using
130 each of fixed size (set at queue creation time).
131 Fixed length mode is deprecated in favour of variable length mode.
135 function creates a new variable length asynchronous logging queue.
138 argument is the name of the file to open for logging.
139 If the file does not yet exist,
141 will attempt to create it.
144 argument will be passed to
146 as the requested creation mode, to be used if the file will be created by
148 Consumers of this API may wish to pass
149 .Dv ALQ_DEFAULT_CMODE ,
150 a default creation mode suitable for most applications.
153 argument specifies the credentials to use when opening and performing I/O on the file.
156 argument sets the size (in bytes) of the underlying queue.
157 The ALQ_ORDERED flag may be passed in via
159 to indicate that the ordering of writer threads waiting for a busy
161 to free up resources should be preserved.
165 function is implemented as a wrapper around
167 to provide backwards compatibility to consumers that have not been updated to
171 It passes all arguments through to
180 To create a variable length mode
184 argument should be set to the size (in bytes) of the underlying queue and the
186 argument should be set to 0.
187 To create a fixed length mode
191 argument should be set to the size (in bytes) of each write and the
193 argument should be set to the number of
195 byte chunks to reserve capacity for.
203 to the designated variable length mode queue
207 could not write the entry immediately and
211 the function will be allowed to
218 A write will automatically schedule the queue
220 to be flushed to disk.
221 This behaviour can be controlled by passing ALQ_NOACTIVATE via
223 to indicate that the write should not schedule
225 to be flushed to disk.
229 function is implemented as a wrapper around
231 to provide backwards compatibility to consumers that have not been updated to
232 utilise variable length mode queues.
233 The function will write
237 was specified at queue creation time) from the
241 Note that it is an error to call
243 on a variable length mode queue.
247 function is used for flushing
249 to the log medium that was passed to
253 has data to flush and is not already in the process of being flushed, the
254 function will block doing IO.
255 Otherwise, the function will return immediately.
259 function will close the asynchronous logging queue
261 and flush all pending write requests to the log medium.
262 It will free all resources that were previously allocated.
266 function returns an asynchronous log entry from
268 initialised to point at a buffer capable of receiving
273 in a locked state, until a subsequent
282 bytes of buffer immediately and
286 the function will be allowed to
293 The caller can choose to write less than
295 bytes of data to the returned asynchronous log entry by setting the entry's
296 ae_bytesused field to the number of bytes actually written.
297 This must be done prior to calling
302 function is implemented as a wrapper around
304 to provide backwards compatibility to consumers that have not been updated to
305 utilise variable length mode queues.
306 The asynchronous log entry returned will be initialised to point at a buffer
311 was specified at queue creation time).
312 Note that it is an error to call
314 on a variable length mode queue.
318 function schedules the asynchronous log entry
326 The ALQ_NOACTIVATE flag may be passed in via
328 to indicate that the queue should not be immediately scheduled to be flushed to
332 in an unlocked state.
336 function is implemented as a wrapper around
338 to provide backwards compatibility to consumers that have not been updated to
342 It simply passes all arguments through to
347 .Sh IMPLEMENTATION NOTES
352 functions both perform a
356 buffer into the underlying
359 Performance critical code paths may wish to consider using
361 (variable length queues) or
363 (fixed length queues) to avoid the extra memory copy. Note that a queue
364 remains locked between calls to
372 so this method of writing to a queue is unsuitable for situations where the
373 time between calls may be substantial.
375 Each asynchronous logging queue is protected by a spin mutex.
381 may attempt to acquire an internal sleep mutex, and should
382 consequently not be used in contexts where sleeping is
387 function returns one of the error codes listed in
391 or else it returns 0.
403 and either the queue is full or the system is shutting down.
415 and either the queue is full or the system is shutting down.
417 NOTE: invalid arguments to non-void functions will result in
427 Asynchronous Logging Queues (ALQ) facility first appeared in
433 facility was written by
434 .An Jeffrey Roberson Aq jeff@FreeBSD.org
436 .An Lawrence Stewart Aq lstewart@freebsd.org .
438 This manual page was written by
439 .An Hiten Pandya Aq hmp@FreeBSD.org
441 .An Lawrence Stewart Aq lstewart@freebsd.org .