Add documentation for taskqueue apis.
This commit is contained in:
Doug Rabson
parent
2ce54ad34d
commit
823234556f
@ -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>
|
||||
|
||||
203
share/man/man9/taskqueue.9
Normal file
203
share/man/man9/taskqueue.9
Normal file
@ -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 .
|
||||
Loading…
x
Reference in New Issue
Block a user