Add documentation for taskqueue apis.

2 files changed, 213 insertions, 1 deletions

diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index 01056ed..29fe6d6 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -36,7 +36,7 @@ MAN9+=	device.9 device_add_child.9 device_delete_child.9 device_enable.9 \
 	bus_generic_print_child.9 bus_generic_read_ivar.9 \
 	bus_generic_shutdown.9 \
 	VOP_ACLCHECK.9 VOP_GETACL.9 VOP_GETEXTATTR.9 VOP_SETACL.9 \
-	VOP_SETEXTATTR.9 acl.9 extattr.9 kobj.9
+	VOP_SETEXTATTR.9 acl.9 extattr.9 kobj.9 taskqueue.9
 
 MLINKS+=MD5.9 MD5Init.9 MD5.9 MD5Transform.9
 MLINKS+=VOP_ATTRIB.9 VOP_GETATTR.9
@@ -112,4 +112,13 @@ MLINKS+=kobj.9 kobj_init.9
 MLINKS+=kobj.9 kobj_delete.9
 MLINKS+=kobj.9 DEFINE_CLASS.9
 
+MLINKS+=taskqueue.9 taskqueue_create.9
+MLINKS+=taskqueue.9 taskqueue_free.9
+MLINKS+=taskqueue.9 taskqueue_find.9
+MLINKS+=taskqueue.9 taskqueue_enqueue.9
+MLINKS+=taskqueue.9 taskqueue_run.9
+MLINKS+=taskqueue.9 TASK_INIT.9
+MLINKS+=taskqueue.9 TASKQUEUE_DECLARE.9
+MLINKS+=taskqueue.9 TASKQUEUE_DEFINE.9
+
 .include <bsd.prog.mk>
diff --git a/share/man/man9/taskqueue.9 b/share/man/man9/taskqueue.9
new file mode 100644
index 0000000..a1ece9f
--- /dev/null
+++ b/share/man/man9/taskqueue.9
@@ -0,0 +1,203 @@
+.\" -*- nroff -*-
+.\"
+.\" Copyright (c) 2000 Doug Rabson
+.\"
+.\" All rights reserved.
+.\"
+.\" This program is free software.
+.\"
+.\" 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. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``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 DEVELOPERS 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.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd May 12, 2000
+.Dt TASKQUEUE 9
+.Os
+.Sh NAME
+.Nm taskqueue
+.Nd asynchronous task execution
+.Sh SYNOPSIS
+.Fd #include <sys/param.h>
+.Fd #include <sys/queue.h>
+.Fd #include <sys/taskqueue.h>
+.Bd -literal
+
+typedef void (*task_fn)(void *context, int pending);
+
+typedef void (*taskqueue_enqueue_fn)(void *context);
+
+struct task {
+	STAILQ_ENTRY(task)	ta_link;	/* link for queue */
+	int			ta_pending;	/* count times queued */
+	int			ta_priority;	/* priority of task in queue */
+	task_fn			ta_func;	/* task handler */
+	void			*ta_context;	/* argument for handler */
+};
+
+.Ed
+.Ft struct taskqueue *
+.Fn taskqueue_create "const char *name" "int mflags" "taskqueue_enqueue_fn enqueue" "void *context"
+.Ft void
+.Fn taskqueue_free "struct taskqueue *queue"
+.Ft struct taskqueue *
+.Fn taskqueue_find "const char *name"
+.Ft int
+.Fn taskqueue_enqueue "struct taskqueue *queue" "struct task *task"
+.Ft void
+.Fn taskqueue_run "struct taskqueue *queue"
+.Fn TASK_INIT "task" "priority" "func" "context"
+.Fn TASKQUEUE_DECLARE "name"
+.Fn TASKQUEUE_DEFINE "name" "enqueue" "context" "init"
+.Sh DESCRIPTION
+.Pp
+These functions provide a simple interface for asynchronous execution
+of code.
+.Pp
+The function
+.Fn taskqueue_create
+is used to create new queues.
+The arguments to
+.Fn taskqueue_create
+include a name which should be unique,
+a set of
+.Xr malloc 9
+flags which specify whether the call to
+.Fn malloc
+is allowed to sleep
+and a function which is called from
+.Fn taskqueue_enqueue
+when a task is added to the queue
+.\" XXX	The rest of the sentence gets lots in relation to the first part.
+to allow the queue to arrange to be run later
+(for instance by scheduling a software interrupt or waking a kernel
+thread).
+.Pp
+The function
+.Fn taskqueue_free
+should be used to remove the queue from the global list of queues
+and free the memory used by the queue.
+Any tasks which are on the queue will be executed at this time.
+.Pp
+The system maintains a list of all queues which can be searched using
+.Fn taskqueue_find .
+The first queue whose name matches is returned, otherwise
+.Dv NULL .
+.Pp
+To add a task to the list of tasks queued on a taskqueue, call
+.Fn taskqueue_enqueue
+with pointers to the queue and task.
+If the task's
+.Va ta_pending
+field is non-zero,
+then it is simply incremented to reflect the number of times the task
+was enqueued.
+Otherwise,
+the task is added to the list before the first task which has a lower
+.Va ta_priority
+value or at the end of the list if no tasks have a lower priority.
+Enqueueing a task does not perform any memory allocation which makes
+it suitable for calling from an interrupt handler.
+This function will return
+.Dv EPIPE
+if the queue is being freed.
+.Pp
+To execute all the tasks on a queue,
+call
+.Fn taskqueue_run .
+When a task is executed,
+first it is removed from the queue,
+the value of
+.Va ta_pending
+is recorded and then the field is zeroed.
+The function
+.Va ta_func
+from the task structure is called with the value of the field
+.Va ta_context
+as its first argument
+and the value of
+.Va ta_pending
+as its second argument.
+.Pp
+A convenience macro,
+.Fn TASK_INIT "task" "priority" "func" "context"
+is provided to initialise a
+.Va task
+structure.
+The values of
+.Va priority ,
+.Va func ,
+and
+.Va context
+are simply copied into the task structure fields and the
+.Va ta_pending
+field is cleared.
+.Pp
+Two macros
+.Fn TASKQUEUE_DECLARE "name"
+and
+.Fn TASKQUEUE_DEFINE "name" "enqueue" "context" "init"
+are used to declare a reference to a global queue
+and to define the implementation of the queue.
+The
+.Fn TASKQUEUE_DEFINE
+macro arranges to call
+.Fn taskqueue_create
+with the values of its
+.Va name ,
+.Va enqueue
+and
+.Va context
+arguments during system initialisation.
+After calling
+.Fn taskqueue_create ,
+the
+.Va init
+argument to the macro is executed as a C statement,
+allowing any further initialisation to be performed
+(such as registering an interrupt handler etc.)
+.Pp
+The system provides a global taskqueue,
+.Va taskqueue_swi ,
+which is run via a software interrupt mechanism.
+To use this queue,
+call
+.Fn taskqueue_enqueue
+with the value of the global variable
+.Va taskqueue_swi .
+The queue will be run at
+.\" XXX	This should be a cross-reference (Xr), but there is no MANLINKS
+.\"	entry for splsofttq.9 yet.
+.Fn splsofttq .
+.Pp
+This queue can be used,
+for instance, for implementing interrupt handlers which must perform a
+significant amount of processing in the handler.
+The hardware interrupt handler would perform minimal processing of the
+interrupt and then enqueue a task to finish the work.
+This reduces to a minimum
+the amount of time spent with interrupts disabled.
+.Sh HISTORY
+This interface first appeared in
+.Fx 5.0 .
+There is a similar facility called tqueue in the Linux kernel.
+.Sh AUTHORS
+This man page was written by
+.An Doug Rabson .