.\"	$OpenBSD: workq_add_task.9,v 1.14 2009/09/03 15:10:39 jmc Exp $
.\"
.\" Copyright (c) 2007 David Gwynne <dlg@openbsd.org>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: September 3 2009 $
.Dt WORKQ_ADD_TASK 9
.Os
.Sh NAME
.Nm workq_add_task ,
.Nm workq_queue_task ,
.Nm workq_create ,
.Nm workq_destroy
.Nd work queues
.Sh SYNOPSIS
.Fd #include <sys/workq.h>
.Ft int
.Fn "workq_add_task" "struct workq *wq" "int flags" "void (*func)(void *, void *)" "void *arg1" "void *arg2"
.Ft void
.Fn "workq_queue_task" "struct workq *wq" "struct workq_task *wqt" "int flags" "void (*func)(void *, void *)" "void *arg1" "void *arg2"
.Ft struct workq *
.Fn "workq_create" "const char *name" "int maxthreads" "int ipl"
.Ft void
.Fn "workq_destroy" "struct workq *wq"
.Sh DESCRIPTION
The
workq
framework API provides a mechanism to defer tasks to a process context when
it is impossible to run such a task in the current context.
.Pp
.Fn workq_add_task
adds a task to the workq specified by the
.Pa wq
argument.
If
.Pa wq
is
.Dv NULL
the task will be run by the kernel's generic work queue.
Tasks in the kernel's generic work queue should not run for long periods of
time, they should use their own workq for task processing.
A task is specified by the
.Pa func
argument, and will be called with
.Pa arg1
and
.Pa arg2 .
Two arguments are allowed to provide additional flexibility to the called
function.
In many cases, one may wish to perform an action on a target.
Two arguments allow both target and action to be passed without
the need for a wrapper struct to contain them in a single argument.
The
.Pa flags
argument specifies creation and runtime characteristics of the task.
The possible flags are:
.Pp
.Bl -tag -offset indent -width WQ_WAITOKXXX -compact
.It Dv WQ_WAITOK
Wait for resources to become available.
If resources are not available and this flag is not set then
.Fn workq_add_task
will return
.Dv ENOMEM .
.El
.Pp
.Fn workq_queue_task
adds a task to the workq specified by the
.Pa wq
argument, using the memory provided by the
.Pa wqt
argument to store that task's entry on the workq.
The
.Pa flags ,
.Pa func ,
.Pa arg1 ,
and
.Pa arg2
arguments are the same as those in the
.Fn workq_add_task
function.
However, because the caller is responsible for providing the memory
needed to store the task on the workq,
.Fn workq_queue_task
is guaranteed to succeed.
.Pp
.Fn workq_create
creates a workq to be used when tasks would unnecessarily block the kernel
workq.
The
.Pa name
argument specifies the name of the kernel threads that run the tasks.
.Pa maxthreads
specifies the maximum number of worker threads that will service the work
queue.
.Pa ipl
specifies the interrupt protection level at which the workq can be safely used.
See
.Xr spl 9
for a list of the IPLs.
.Pp
.Fn workq_destroy
causes the resources associated with a previously created workq to be freed.
It will wait till all the tasks in the work queue are completed before
returning.
.Pp
.Fn workq_add_task ,
.Fn workq_create ,
and
.Fn workq_destroy
can be called during
.Xr autoconf 9
or from process context.
.Fn workq_add_task
can additionally be called from interrupt context if
.Dv WQ_WAITOK
is not specified.
.Sh SEE ALSO
.Xr autoconf 9 ,
.Xr spl 9
.Sh HISTORY
The workq framework was originally written by
.An Ted Unangst Aq tedu@openbsd.org ,
and heavily influenced by arguments with
.An David Gwynne Aq dlg@openbsd.org .
The workq framework first appeared in
.Ox 4.2 .