231 lines
7.1 KiB
Groff
231 lines
7.1 KiB
Groff
.\" -*- 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
|
|
.In sys/param.h
|
|
.In sys/kernel.h
|
|
.In sys/malloc.h
|
|
.In sys/queue.h
|
|
.In 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 int
|
|
.Fn taskqueue_enqueue_fast "struct taskqueue *queue" "struct task *task"
|
|
.Ft void
|
|
.Fn taskqueue_run "struct taskqueue *queue"
|
|
.Fn TASK_INIT "struct task *task" "int priority" "task_fn_t *func" "void *context"
|
|
.Fn TASKQUEUE_DECLARE "name"
|
|
.Fn TASKQUEUE_DEFINE "name" "taskqueue_enqueue_fn enqueue" "void *context" "init"
|
|
.Sh DESCRIPTION
|
|
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
|
|
.Er EPIPE
|
|
if the queue is being freed.
|
|
.Pp
|
|
The function
|
|
.Fn taskqueue_enqueue_fast
|
|
should be used in place of
|
|
.Fn taskqueue_enqueue
|
|
when the enqueuing must happen from a fast interrupt handler.
|
|
This method uses spin locks to avoid the possibility of sleeping in the fast
|
|
interrupt context.
|
|
.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 three global taskqueues,
|
|
.Va taskqueue_swi ,
|
|
.Va taskqueue_swi_giant ,
|
|
and
|
|
.Va taskqueue_thread .
|
|
The swi taskqueues are run via a software interrupt mechanism.
|
|
The taskqueue_swi queue runs without the protection of the Giant kernel lock,
|
|
and the taskqueue_swi_giant queue runs with the protection of the Giant
|
|
kernel lock.
|
|
The thread taskqueue runs in a kernel thread context, and tasks run from
|
|
this thread do not run under the Giant kernel lock.
|
|
If the caller wants to run under Giant, he should explicitly acquire and
|
|
release Giant in his taskqueue handler routine.
|
|
|
|
To use these queues,
|
|
call
|
|
.Fn taskqueue_enqueue
|
|
with the value of the global taskqueue variable for the queue you wish to
|
|
use (
|
|
.Va taskqueue_swi ,
|
|
.Va taskqueue_swi_giant ,
|
|
or
|
|
.Va taskqueue_thread
|
|
).
|
|
.Pp
|
|
The software interrupt queues 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.
|
|
.Pp
|
|
The thread queue can be used, for instance, by interrupt level routines
|
|
that need to call kernel functions that do things that can only be done
|
|
from a thread context.
|
|
(e.g., call malloc with the M_WAITOK flag.)
|
|
.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 .
|