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
  87 The
  88 .Nm
  89 facility provides an asynchronous fixed or variable length recording
  90 mechanism, known as Asynchronous Logging Queues.
  91 It can record to any
  92 .Xr vnode 9 ,
  93 thus providing the ability to journal logs to character
  94 devices as well as regular files.
  95 All functions accept a
  96 .Vt "struct alq"
  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.
 101 .Pp
 102 An
 103 .Dq asynchronous log entry
 104 is defined as
 105 .Vt "struct ale" ,
 106 which has the following members:
 107 .Bd -literal -offset indent
 108 struct 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
 115 An
 116 .Nm
 117 can be created in either fixed or variable length mode.
 118 A variable length
 119 .Nm
 120 accommodates writes of varying length using
 121 .Fn alq_writen
 122 and
 123 .Fn alq_getn .
 124 A fixed length
 125 .Nm
 126 accommodates a fixed number of writes using
 127 .Fn alq_write
 128 and
 129 .Fn alq_get ,
 130 each of fixed size (set at queue creation time).
 131 Fixed length mode is deprecated in favour of variable length mode.
 132 .Sh FUNCTIONS
 133 The
 134 .Fn alq_open_flags
 135 function creates a new variable length asynchronous logging queue.
 136 The
 137 .Fa file
 138 argument is the name of the file to open for logging.
 139 If the file does not yet exist,
 140 .Fn alq_open
 141 will attempt to create it.
 142 The
 143 .Fa cmode
 144 argument will be passed to
 145 .Fn vn_open
 146 as the requested creation mode, to be used if the file will be created by
 147 .Fn alq_open .
 148 Consumers of this API may wish to pass
 149 .Dv ALQ_DEFAULT_CMODE ,
 150 a default creation mode suitable for most applications.
 151 The
 152 .Fa cred
 153 argument specifies the credentials to use when opening and performing I/O on the file.
 154 The
 155 .Fa size
 156 argument sets the size (in bytes) of the underlying queue.
 157 The ALQ_ORDERED flag may be passed in via
 158 .Fa flags
 159 to indicate that the ordering of writer threads waiting for a busy
 160 .Nm
 161 to free up resources should be preserved.
 162 .Pp
 163 The deprecated
 164 .Fn alq_open
 165 function is implemented as a wrapper around
 166 .Fn alq_open_flags
 167 to provide backwards compatibility to consumers that have not been updated to
 168 utilise the newer
 169 .Fn alq_open_flags
 170 function.
 171 It passes all arguments through to
 172 .Fn alq_open_flags
 173 untouched except for
 174 .Fa size
 175 and
 176 .Fa count ,
 177 and sets
 178 .Fa flags
 179 to 0.
 180 To create a variable length mode
 181 .Nm ,
 182 the
 183 .Fa size
 184 argument should be set to the size (in bytes) of the underlying queue and the
 185 .Fa count
 186 argument should be set to 0.
 187 To create a fixed length mode
 188 .Nm ,
 189 the
 190 .Fa size
 191 argument should be set to the size (in bytes) of each write and the
 192 .Fa count
 193 argument should be set to the number of
 194 .Fa size
 195 byte chunks to reserve capacity for.
 196 .Pp
 197 The
 198 .Fn alq_writen
 199 function writes
 200 .Fa len
 201 bytes from
 202 .Fa data
 203 to the designated variable length mode queue
 204 .Fa alq .
 205 If
 206 .Fn alq_writen
 207 could not write the entry immediately and
 208 .Dv ALQ_WAITOK
 209 is set in
 210 .Fa flags ,
 211 the function will be allowed to
 212 .Xr msleep_spin 9
 213 with the
 214 .Dq Li alqwnord
 215 or
 216 .Dq Li alqwnres
 217 wait message.
 218 A write will automatically schedule the queue
 219 .Fa alq
 220 to be flushed to disk.
 221 This behaviour can be controlled by passing ALQ_NOACTIVATE via
 222 .Fa flags
 223 to indicate that the write should not schedule
 224 .Fa alq
 225 to be flushed to disk.
 226 .Pp
 227 The deprecated
 228 .Fn alq_write
 229 function is implemented as a wrapper around
 230 .Fn alq_writen
 231 to provide backwards compatibility to consumers that have not been updated to
 232 utilise variable length mode queues.
 233 The function will write
 234 .Fa size
 235 bytes of data (where
 236 .Fa size
 237 was specified at queue creation time) from the
 238 .Fa data
 239 buffer to the
 240 .Fa alq .
 241 Note that it is an error to call
 242 .Fn alq_write
 243 on a variable length mode queue.
 244 .Pp
 245 The
 246 .Fn alq_flush
 247 function is used for flushing
 248 .Fa alq
 249 to the log medium that was passed to
 250 .Fn alq_open .
 251 If
 252 .Fa alq
 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.
 256 .Pp
 257 The
 258 .Fn alq_close
 259 function will close the asynchronous logging queue
 260 .Fa alq
 261 and flush all pending write requests to the log medium.
 262 It will free all resources that were previously allocated.
 263 .Pp
 264 The
 265 .Fn alq_getn
 266 function returns an asynchronous log entry from
 267 .Fa alq ,
 268 initialised to point at a buffer capable of receiving
 269 .Fa len
 270 bytes of data.
 271 This function leaves
 272 .Fa alq
 273 in a locked state, until a subsequent
 274 .Fn alq_post
 275 or
 276 .Fn alq_post_flags
 277 call is made.
 278 If
 279 .Fn alq_getn
 280 could not obtain
 281 .Fa len
 282 bytes of buffer immediately and
 283 .Dv ALQ_WAITOK
 284 is set in
 285 .Fa flags ,
 286 the function will be allowed to
 287 .Xr msleep_spin 9
 288 with the
 289 .Dq Li alqgnord
 290 or
 291 .Dq Li alqgnres
 292 wait message.
 293 The caller can choose to write less than
 294 .Fa len
 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
 298 .Fn alq_post .
 299 .Pp
 300 The deprecated
 301 .Fn alq_get
 302 function is implemented as a wrapper around
 303 .Fn alq_getn
 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
 307 capable of receiving
 308 .Fa size
 309 bytes of data (where
 310 .Fa size
 311 was specified at queue creation time).
 312 Note that it is an error to call
 313 .Fn alq_get
 314 on a variable length mode queue.
 315 .Pp
 316 The
 317 .Fn alq_post_flags
 318 function schedules the asynchronous log entry
 319 .Fa ale
 320 (obtained from
 321 .Fn alq_getn
 322 or
 323 .Fn alq_get )
 324 for writing to
 325 .Fa alq .
 326 The ALQ_NOACTIVATE flag may be passed in via
 327 .Fa flags
 328 to indicate that the queue should not be immediately scheduled to be flushed to
 329 disk.
 330 This function leaves
 331 .Fa alq
 332 in an unlocked state.
 333 .Pp
 334 The
 335 .Fn alq_post
 336 function is implemented as a wrapper around
 337 .Fn alq_post_flags
 338 to provide backwards compatibility to consumers that have not been updated to
 339 utilise the newer
 340 .Fn alq_post_flags
 341 function.
 342 It simply passes all arguments through to
 343 .Fn alq_post_flags
 344 untouched, and sets
 345 .Fa flags
 346 to 0.
 347 .Sh IMPLEMENTATION NOTES
 348 The
 349 .Fn alq_writen
 350 and
 351 .Fn alq_write
 352 functions both perform a
 353 .Xr bcopy 3
 354 from the supplied
 355 .Fa data
 356 buffer into the underlying
 357 .Nm
 358 buffer.
 359 Performance 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
 364 remains locked between calls to
 365 .Fn alq_getn
 366 or
 367 .Fn alq_get
 368 and
 369 .Fn alq_post
 370 or
 371 .Fn alq_post_flags ,
 372 so this method of writing to a queue is unsuitable for situations where the
 373 time between calls may be substantial.
 374 .Sh LOCKING
 375 Each asynchronous logging queue is protected by a spin mutex.
 376 .Pp
 377 Functions
 378 .Fn alq_flush
 379 and
 380 .Fn alq_open
 381 may attempt to acquire an internal sleep mutex, and should
 382 consequently not be used in contexts where sleeping is
 383 not allowed.
 384 .Sh RETURN VALUES
 385 The
 386 .Fn alq_open
 387 function returns one of the error codes listed in
 388 .Xr open 2 ,
 389 if it fails to open
 390 .Fa file ,
 391 or else it returns 0.
 392 .Pp
 393 The
 394 .Fn alq_writen
 395 and
 396 .Fn alq_write
 397 functions return
 398 .Er EWOULDBLOCK
 399 if
 400 .Dv ALQ_NOWAIT
 401 was set in
 402 .Fa flags
 403 and either the queue is full or the system is shutting down.
 404 .Pp
 405 The
 406 .Fn alq_getn
 407 and
 408 .Fn alq_get
 409 functions return
 410 .Dv NULL
 411 if
 412 .Dv ALQ_NOWAIT
 413 was set in
 414 .Fa flags
 415 and either the queue is full or the system is shutting down.
 416 .Pp
 417 NOTE: invalid arguments to non-void functions will result in
 418 undefined 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
 426 The
 427 Asynchronous Logging Queues (ALQ) facility first appeared in
 428 .Fx 5.0 .
 429 .Sh AUTHORS
 430 .An -nosplit
 431 The
 432 .Nm
 433 facility was written by
 434 .An Jeffrey Roberson Aq jeff@FreeBSD.org
 435 and extended by
 436 .An Lawrence Stewart Aq lstewart@freebsd.org .
 437 .Pp
 438 This manual page was written by
 439 .An Hiten Pandya Aq hmp@FreeBSD.org
 440 and revised by
 441 .An Lawrence Stewart Aq lstewart@freebsd.org .