An
alq
can be created in either fixed or variable length mode.
A variable length
alq
accommodates writes of varying length using
alq_writen()
and
alq_getn().
A fixed length
alq
accommodates a fixed number of writes using
alq_write()
and
alq_get(),
each of fixed size (set at queue creation time).
Fixed length mode is deprecated in favour of variable length mode.

The deprecated
alq_write()
function is implemented as a wrapper around
alq_writen()
to provide backwards compatibility to consumers that have not been updated to
utilise variable length mode queues.
The function will write
size
bytes of data (where
size
was specified at queue creation time) from the
data
buffer to the
alq.
Note that it is an error to call
alq_write()
on a variable length mode queue.

The
alq_flush()
function is used for flushing
alq
to the log medium that was passed to
alq_open().
If
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
alq_close()
function will close the asynchronous logging queue
alq
and flush all pending write requests to the log medium.
It will free all resources that were previously allocated.

The
alq_getn()
function returns an asynchronous log entry from
alq,
initialised to point at a buffer capable of receiving
len
bytes of data.
This function leaves
alq
in a locked state, until a subsequent
alq_post()
or
alq_post_flags()
call is made.
If
alq_getn()
could not obtain
len
bytes of buffer immediately and
ALQ_WAITOK
is set in
flags,
the function will be allowed to
msleep_spin(9)
with the
"alqgnord"
or
"alqgnres"
wait message.
The caller can choose to write less than
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
alq_post().

The deprecated
alq_get()
function is implemented as a wrapper around
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
size
bytes of data (where
size
was specified at queue creation time).
Note that it is an error to call
alq_get()
on a variable length mode queue.

The
alq_post_flags()
function schedules the asynchronous log entry
ale
(obtained from
alq_getn()
or
alq_get())
for writing to
alq.
The ALQ_NOACTIVATE flag may be passed in via
flags
to indicate that the queue should not be immediately scheduled to be flushed to
disk.
This function leaves
alq
in an unlocked state.

The
alq_post()
function is implemented as a wrapper around
alq_post_flags()
to provide backwards compatibility to consumers that have not been updated to
utilise the newer
alq_post_flags()
function.
It simply passes all arguments through to
alq_post_flags()
untouched, and sets
flags
to 0.

The
alq_writen()
and
alq_write()
functions both perform a
bcopy(3)
from the supplied
data
buffer into the underlying
alq
buffer.
Performance critical code paths may wish to consider using
alq_getn()
(variable length queues) or
alq_get()
(fixed length queues) to avoid the extra memory copy.
Note that a queue remains locked between calls to
alq_getn()
or
alq_get()
and
alq_post()
or
alq_post_flags(),
so this method of writing to a queue is unsuitable for situations where the
time between calls may be substantial.