alq_getn (9)

Leading comments

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...

(The comments found at the beginning of the groff file "man9/alq_getn.9freebsd".)

NAME

alq alq_open_flags alq_open alq_writen alq_write alq_flush alq_close alq_getn alq_get alq_post_flags alq_post - Asynchronous Logging Queues

SYNOPSIS

In 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

DESCRIPTION

The facility provides an asynchronous fixed or variable length recording mechanism, known as Asynchronous Logging Queues. It can record to any 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.

An ``asynchronous log entry'' is defined as Vt struct ale , which has the following members:

struct ale {
        intptr_t        ae_bytesused;   /* # bytes written to ALE. */
        char            *ae_data;       /* Write ptr. */
        int             ae_pad;         /* Unused, compat. */
};

An can be created in either fixed or variable length mode. A variable length accommodates writes of varying length using Fn alq_writen and Fn alq_getn . A fixed length 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.

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 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 to free up resources should be preserved.

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 , 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 , 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.

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 ALQ_WAITOK is set in Fa flags , the function will be allowed to msleep_spin9 with the ``alqwnord '' or ``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.

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.

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.

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.

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 ALQ_WAITOK is set in Fa flags , the function will be allowed to msleep_spin9 with the ``alqgnord '' or ``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 .

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.

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.

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.

IMPLEMENTATION NOTES

The Fn alq_writen and Fn alq_write functions both perform a bcopy(3) from the supplied Fa data buffer into the underlying 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.

LOCKING

Each asynchronous logging queue is protected by a spin mutex.

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.

RETURN VALUES

The Fn alq_open function returns one of the error codes listed in open(2), if it fails to open Fa file , or else it returns 0.

The Fn alq_writen and Fn alq_write functions return Er EWOULDBLOCK if ALQ_NOWAIT was set in Fa flags and either the queue is full or the system is shutting down.

The Fn alq_getn and Fn alq_get functions return NULL if ALQ_NOWAIT was set in Fa flags and either the queue is full or the system is shutting down.

NOTE: invalid arguments to non-void functions will result in undefined behaviour.

SEE ALSO

syslog(3), kproc(9), ktr(9), msleep_spin9, vnode(9)

HISTORY

The Asynchronous Logging Queues (ALQ) facility first appeared in Fx 5.0 .

AUTHORS

An -nosplit The facility was written by An Jeffrey Roberson Aq Mt jeff@FreeBSD.org and extended by An Lawrence Stewart Aq Mt lstewart@freebsd.org .

This manual page was written by An Hiten Pandya Aq Mt hmp@FreeBSD.org and revised by An Lawrence Stewart Aq Mt lstewart@freebsd.org .