1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
|
.\" $OpenBSD: task_add.9,v 1.6 2013/12/09 01:54:49 dlg Exp $
.\"
.\" Copyright (c) 2013 David Gwynne <dlg@openbsd.org>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: December 9 2013 $
.Dt TASK_ADD 9
.Os
.Sh NAME
.Nm taskq_create ,
.Nm taskq_destroy ,
.Nm task_set ,
.Nm task_add ,
.Nm task_del
.Nd task queues
.Sh SYNOPSIS
.In sys/task.h
.Ft struct taskq *
.Fn "taskq_create" "const char *name" "unsigned int nthreads" "int ipl"
.Ft void
.Fn "taskq_destroy" "struct taskq *tq"
.Ft void
.Fn "task_set" "struct task *t" "void (*fn)(void *, void *)" "void *arg1" "void *arg2"
.Ft int
.Fn "task_add" "struct taskq *tq" "struct task *t"
.Ft int
.Fn "task_del" "struct taskq *tq" "struct task *t"
.Vt extern struct taskq *const systq;
.Sh DESCRIPTION
The
taskq
API provides a mechanism to defer work to a process context.
.Pp
.Fn taskq_create
allocates a taskq and a set of threads to be used to complete work
that would be inappropriate for the shared system taskq.
The
.Pa name
argument specifies the name of the kernel threads that are created
to service the work on the taskq.
.Pa nthreads
specifies the number of threads that will be created to handle the work.
.Pa ipl
specifies the highest interrupt protection level at which
.Fn task_add
and
.Fn task_del
will be called against the created taskq.
See
.Xr spl 9
for a list of the IPLs.
.Pp
.Fn taskq_destroy
causes the resources associated with a previously created taskq to be freed.
It will wait till all the tasks in the work queue are completed before
returning.
Calling
.Fn taskq_destroy
against the system taskq is an error and will lead to undefined
behaviour or a system fault.
.Pp
It is the responsibility of the caller to provide the
.Fn task_set ,
.Fn task_add ,
and
.Fn task_del
functions with pre-allocated task structures.
.Pp
.Fn task_set
prepares the task structure
.Fa t
to be used in future calls to
.Fn task_add
and
.Fn task_del .
.Fa t
will be prepared to call the function
.Fa fn
with the arguments specified by
.Fa arg1
and
.Fa arg2 .
Once initialised, the
.Fa t
structure can be used repeatedly in calls to
.Fn task_add
and
.Fn task_del
and does not need to be reinitialised unless the function called
and/or its argument must change.
.Pp
.Fn task_add
schedules the execution of the work specified by the
task structure
.Fa t
on the
.Fa tq
taskq.
The task structure must already be initialised by
.Fn task_set .
.Fn task_add
will return 1 if
.Fa t
was added to the taskq or 0 if it was already on the taskq.
.Pp
.Fn task_del
will remove the task structure
.Fa t
from the taskq
.Fa tq .
If the work was already executed or has not been added to the taskq,
the call will have no effect.
Calling
.Fn task_del
against a different taskq than the one given in a previous call to
.Fn task_add
is an error and will lead to undefined behaviour.
If the work was actually removed from the taskq it will return 1, otherwise 0.
.Pp
The kernel provides a system taskq
.Va systq
that can be used by any subsystem for short lived tasks.
It is serviced by a single thread and can therefore provide predictable
ordering of work.
Work can be scheduled on the system taskq from callers at or below IPL_HIGH.
.Pp
.Fn taskq_create
and
.Fn taskq_destroy
can be called during autoconf, or from process context.
.Fn task_set ,
.Fn task_add ,
and
.Fn task_del
can be called during autoconf, from process context, or from interrupt context.
.Sh SEE ALSO
.Xr autoconf 9 ,
.Xr spl 9
.Sh HISTORY
The task API was originally written by
.An David Gwynne Aq Mt dlg@openbsd.org .
The task API first appeared in
.Ox 5.5 .
|
