/share/man/man9/alq.9

  1.\"
  2.\" Copyright (c) 2003 Hiten Pandya <hmp@FreeBSD.org>
  3.\" Copyright (c) 2009-2010 The FreeBSD Foundation
  4.\" All rights reserved.
  5.\"
  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
  9.\" Foundation.
 10.\"
 11.\" Redistribution and use in source and binary forms, with or without
 12.\" modification, are permitted provided that the following conditions
 13.\" are met:
 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.
 19.\"
 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
 30.\" SUCH DAMAGE.
 31.\"
 32.\" $FreeBSD$
 33.\"
 34.Dd April 26, 2010
 35.Dt ALQ 9
 36.Os
 37.Sh NAME
 38.Nm alq ,
 39.Nm alq_open_flags ,
 40.Nm alq_open ,
 41.Nm alq_writen ,
 42.Nm alq_write ,
 43.Nm alq_flush ,
 44.Nm alq_close ,
 45.Nm alq_getn ,
 46.Nm alq_get ,
 47.Nm alq_post_flags ,
 48.Nm alq_post
 49.Nd Asynchronous Logging Queues
 50.Sh SYNOPSIS
 51.In sys/alq.h
 52.Ft int
 53.Fo alq_open_flags
 54.Fa "struct alq **app"
 55.Fa "const char *file"
 56.Fa "struct ucred *cred"
 57.Fa "int cmode"
 58.Fa "int size"
 59.Fa "int flags"
 60.Fc
 61.Ft int
 62.Fo alq_open
 63.Fa "struct alq **app"
 64.Fa "const char *file"
 65.Fa "struct ucred *cred"
 66.Fa "int cmode"
 67.Fa "int size"
 68.Fa "int count"
 69.Fc
 70.Ft int
 71.Fn alq_writen "struct alq *alq" "void *data" "int len" "int flags"
 72.Ft int
 73.Fn alq_write "struct alq *alq" "void *data" "int flags"
 74.Ft void
 75.Fn alq_flush "struct alq *alq"
 76.Ft void
 77.Fn alq_close "struct alq *alq"
 78.Ft struct ale *
 79.Fn alq_getn "struct alq *alq" "int len" "int flags"
 80.Ft struct ale *
 81.Fn alq_get "struct alq *alq" "int flags"
 82.Ft void
 83.Fn alq_post_flags "struct alq *alq" "struct ale *ale" "int flags"
 84.Ft void
 85.Fn alq_post "struct alq *alq" "struct ale *ale"
 86.Sh DESCRIPTION
 87The
 88.Nm
 89facility provides an asynchronous fixed or variable length recording
 90mechanism, known as Asynchronous Logging Queues.
 91It can record to any
 92.Xr vnode 9 ,
 93thus providing the ability to journal logs to character
 94devices as well as regular files.
 95All functions accept a
 96.Vt "struct alq"
 97argument, which is an opaque type that maintains state information
 98for an Asynchronous Logging Queue.
 99The logging facility runs in a separate kernel thread, which services
100all log entry requests.
101.Pp
102An
103.Dq asynchronous log entry
104is defined as
105.Vt "struct ale" ,
106which has the following members:
107.Bd -literal -offset indent
108struct ale {
109	intptr_t	ae_bytesused;	/* # bytes written to ALE. */
110	char		*ae_data;	/* Write ptr. */
111	int		ae_pad;		/* Unused, compat. */
112};
113.Ed
114.Pp
115An
116.Nm
117can be created in either fixed or variable length mode.
118A variable length
119.Nm
120accommodates writes of varying length using
121.Fn alq_writen
122and
123.Fn alq_getn .
124A fixed length
125.Nm
126accommodates a fixed number of writes using
127.Fn alq_write
128and
129.Fn alq_get ,
130each of fixed size (set at queue creation time).
131Fixed length mode is deprecated in favour of variable length mode.
132.Sh FUNCTIONS
133The
134.Fn alq_open_flags
135function creates a new variable length asynchronous logging queue.
136The
137.Fa file
138argument is the name of the file to open for logging.
139If the file does not yet exist,
140.Fn alq_open
141will attempt to create it.
142The
143.Fa cmode
144argument will be passed to
145.Fn vn_open
146as the requested creation mode, to be used if the file will be created by
147.Fn alq_open .
148Consumers of this API may wish to pass
149.Dv ALQ_DEFAULT_CMODE ,
150a default creation mode suitable for most applications.
151The
152.Fa cred
153argument specifies the credentials to use when opening and performing I/O on the file.
154The
155.Fa size
156argument sets the size (in bytes) of the underlying queue.
157The ALQ_ORDERED flag may be passed in via
158.Fa flags
159to indicate that the ordering of writer threads waiting for a busy
160.Nm
161to free up resources should be preserved.
162.Pp
163The deprecated
164.Fn alq_open
165function is implemented as a wrapper around
166.Fn alq_open_flags
167to provide backwards compatibility to consumers that have not been updated to
168utilise the newer
169.Fn alq_open_flags
170function.
171It passes all arguments through to
172.Fn alq_open_flags
173untouched except for
174.Fa size
175and
176.Fa count ,
177and sets
178.Fa flags
179to 0.
180To create a variable length mode
181.Nm ,
182the
183.Fa size
184argument should be set to the size (in bytes) of the underlying queue and the
185.Fa count
186argument should be set to 0.
187To create a fixed length mode
188.Nm ,
189the
190.Fa size
191argument should be set to the size (in bytes) of each write and the
192.Fa count
193argument should be set to the number of
194.Fa size
195byte chunks to reserve capacity for.
196.Pp
197The
198.Fn alq_writen
199function writes
200.Fa len
201bytes from
202.Fa data
203to the designated variable length mode queue
204.Fa alq .
205If
206.Fn alq_writen
207could not write the entry immediately and
208.Dv ALQ_WAITOK
209is set in
210.Fa flags ,
211the function will be allowed to
212.Xr msleep_spin 9
213with the
214.Dq Li alqwnord
215or
216.Dq Li alqwnres
217wait message.
218A write will automatically schedule the queue
219.Fa alq
220to be flushed to disk.
221This behaviour can be controlled by passing ALQ_NOACTIVATE via
222.Fa flags
223to indicate that the write should not schedule
224.Fa alq
225to be flushed to disk.
226.Pp
227The deprecated
228.Fn alq_write
229function is implemented as a wrapper around
230.Fn alq_writen
231to provide backwards compatibility to consumers that have not been updated to
232utilise variable length mode queues.
233The function will write
234.Fa size
235bytes of data (where
236.Fa size
237was specified at queue creation time) from the
238.Fa data
239buffer to the
240.Fa alq .
241Note that it is an error to call
242.Fn alq_write
243on a variable length mode queue.
244.Pp
245The
246.Fn alq_flush
247function is used for flushing
248.Fa alq
249to the log medium that was passed to
250.Fn alq_open .
251If
252.Fa alq
253has data to flush and is not already in the process of being flushed, the
254function will block doing IO.
255Otherwise, the function will return immediately.
256.Pp
257The
258.Fn alq_close
259function will close the asynchronous logging queue
260.Fa alq
261and flush all pending write requests to the log medium.
262It will free all resources that were previously allocated.
263.Pp
264The
265.Fn alq_getn
266function returns an asynchronous log entry from
267.Fa alq ,
268initialised to point at a buffer capable of receiving
269.Fa len
270bytes of data.
271This function leaves
272.Fa alq
273in a locked state, until a subsequent
274.Fn alq_post
275or
276.Fn alq_post_flags
277call is made.
278If
279.Fn alq_getn
280could not obtain
281.Fa len
282bytes of buffer immediately and
283.Dv ALQ_WAITOK
284is set in
285.Fa flags ,
286the function will be allowed to
287.Xr msleep_spin 9
288with the
289.Dq Li alqgnord
290or
291.Dq Li alqgnres
292wait message.
293The caller can choose to write less than
294.Fa len
295bytes of data to the returned asynchronous log entry by setting the entry's
296ae_bytesused field to the number of bytes actually written.
297This must be done prior to calling
298.Fn alq_post .
299.Pp
300The deprecated
301.Fn alq_get
302function is implemented as a wrapper around
303.Fn alq_getn
304to provide backwards compatibility to consumers that have not been updated to
305utilise variable length mode queues.
306The asynchronous log entry returned will be initialised to point at a buffer
307capable of receiving
308.Fa size
309bytes of data (where
310.Fa size
311was specified at queue creation time).
312Note that it is an error to call
313.Fn alq_get
314on a variable length mode queue.
315.Pp
316The
317.Fn alq_post_flags
318function schedules the asynchronous log entry
319.Fa ale
320(obtained from
321.Fn alq_getn
322or
323.Fn alq_get )
324for writing to
325.Fa alq .
326The ALQ_NOACTIVATE flag may be passed in via
327.Fa flags
328to indicate that the queue should not be immediately scheduled to be flushed to
329disk.
330This function leaves
331.Fa alq
332in an unlocked state.
333.Pp
334The
335.Fn alq_post
336function is implemented as a wrapper around
337.Fn alq_post_flags
338to provide backwards compatibility to consumers that have not been updated to
339utilise the newer
340.Fn alq_post_flags
341function.
342It simply passes all arguments through to
343.Fn alq_post_flags
344untouched, and sets
345.Fa flags
346to 0.
347.Sh IMPLEMENTATION NOTES
348The
349.Fn alq_writen
350and
351.Fn alq_write
352functions both perform a
353.Xr bcopy 3
354from the supplied
355.Fa data
356buffer into the underlying
357.Nm
358buffer.
359Performance critical code paths may wish to consider using
360.Fn alq_getn
361(variable length queues) or
362.Fn alq_get
363(fixed length queues) to avoid the extra memory copy. Note that a queue
364remains locked between calls to
365.Fn alq_getn
366or
367.Fn alq_get
368and
369.Fn alq_post
370or
371.Fn alq_post_flags ,
372so this method of writing to a queue is unsuitable for situations where the
373time between calls may be substantial.
374.Sh LOCKING
375Each asynchronous logging queue is protected by a spin mutex.
376.Pp
377Functions
378.Fn alq_flush
379and
380.Fn alq_open
381may attempt to acquire an internal sleep mutex, and should
382consequently not be used in contexts where sleeping is
383not allowed.
384.Sh RETURN VALUES
385The
386.Fn alq_open
387function returns one of the error codes listed in
388.Xr open 2 ,
389if it fails to open
390.Fa file ,
391or else it returns 0.
392.Pp
393The
394.Fn alq_writen
395and
396.Fn alq_write
397functions return
398.Er EWOULDBLOCK
399if
400.Dv ALQ_NOWAIT
401was set in
402.Fa flags
403and either the queue is full or the system is shutting down.
404.Pp
405The
406.Fn alq_getn
407and
408.Fn alq_get
409functions return
410.Dv NULL
411if
412.Dv ALQ_NOWAIT
413was set in
414.Fa flags
415and either the queue is full or the system is shutting down.
416.Pp
417NOTE: invalid arguments to non-void functions will result in
418undefined behaviour.
419.Sh SEE ALSO
420.Xr kproc 9 ,
421.Xr ktr 9 ,
422.Xr msleep_spin 9 ,
423.Xr syslog 3 ,
424.Xr vnode 9
425.Sh HISTORY
426The
427Asynchronous Logging Queues (ALQ) facility first appeared in
428.Fx 5.0 .
429.Sh AUTHORS
430.An -nosplit
431The
432.Nm
433facility was written by
434.An Jeffrey Roberson Aq jeff@FreeBSD.org
435and extended by
436.An Lawrence Stewart Aq lstewart@freebsd.org .
437.Pp
438This manual page was written by
439.An Hiten Pandya Aq hmp@FreeBSD.org
440and revised by
441.An Lawrence Stewart Aq lstewart@freebsd.org .