add a manpage for workq stuff.

thanks to jmc for tweaking it. im sure he'll find more changes to make soon

2 files changed, 118 insertions, 2 deletions

diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index 0b0bb864e47..3bb9dd8b366 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -1,4 +1,4 @@
-#	$OpenBSD: Makefile,v 1.127 2007/05/09 19:31:14 claudio Exp $
+#	$OpenBSD: Makefile,v 1.128 2007/05/31 21:41:41 dlg Exp $
 #	$NetBSD: Makefile,v 1.4 1996/01/09 03:23:01 thorpej Exp $
 
 #	Makefile for section 9 (kernel function and variable) manual pages.
@@ -28,7 +28,7 @@ MAN=	altq.9 aml_evalnode.9 atomic.9 audio.9 autoconf.9 bio_register.9 \
 	vfs_cache.9 vaccess.9 vclean.9 vcount.9 vdevgone.9 vfinddev.9 vflush.9 \
 	vflushbuf.9 vget.9 vgone.9 vhold.9 vinvalbuf.9 vnode.9 vnsubr.9 \
 	VOP_GETATTR.9 VOP_LOOKUP.9 vput.9 vrecycle.9 vref.9 vrele.9 \
-	vwaitforio.9 vwakeup.9 wdog_register.9
+	vwaitforio.9 vwakeup.9 wdog_register.9 workq_add_task.9
 
 MLINKS+=aml_evalnode.9 aml_evalname.9 aml_evalnode.9 aml_find_node.9 \
 	aml_evalnode.9 aml_freevalue.9 aml_evalnode.9 aml_val2int.9
@@ -337,5 +337,7 @@ MLINKS+=VOP_LOOKUP.9 VOP_ABORTOP.9 VOP_LOOKUP.9 VOP_ACCESS.9 \
 	VOP_LOOKUP.9 VOP_REVOKE.9 VOP_LOOKUP.9 VOP_RMDIR.9 \
 	VOP_LOOKUP.9 VOP_STRATEGY.9 VOP_LOOKUP.9 VOP_SYMLINK.9 \
 	VOP_LOOKUP.9 VOP_UNLOCK.9 VOP_LOOKUP.9 VOP_WRITE.9
+MLINKS+=workq_add_task.9 workq_create.9 \
+	workq_add_task.9 workq_destroy.9
 
 .include <bsd.prog.mk>
diff --git a/share/man/man9/workq_add_task.9 b/share/man/man9/workq_add_task.9
new file mode 100644
index 00000000000..6cd5bcd9851
--- /dev/null
+++ b/share/man/man9/workq_add_task.9
@@ -0,0 +1,114 @@
+.\"	$OpenBSD: workq_add_task.9,v 1.1 2007/05/31 21:41:41 dlg 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: May 31 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" "void (*func)(void *, void *)" "void *arg1" "void *arg2" "int flags"
+.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 .
+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 Unanst 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 .