.\"	$OpenBSD: workq_add_task.9,v 1.5 2007/06/11 22:13:19 thib Exp $
.\"
.\" Copyright (c) 2007 David Gwynne <dlg@openbsd.org>
.\"
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\"
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. The name of the author may not be used to endorse or promote products
.\"    derived from this software without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
.\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
.\" AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
.\" THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
.\" EXEMPLARY, OR CONSEQUENTIAL  DAMAGES (INCLUDING, BUT NOT LIMITED TO,
.\" PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
.\" OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
.\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
.\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd $Mdocdate: June 11 2007 $
.Dt WORKQ_ADD_TASK 9
.Os
.Sh NAME
.Nm workq_add_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 struct workq *
.Fn "workq_create" "const char *name" "int maxthreads"
.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 NULL .
.El
.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.
.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
.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 .