| blob | 241b20f48699b9a37fe33e340a348e20b653f8e0 |
1 .\" -*- nroff -*-
2 .\"
3 .\" Copyright (c) 2000 Doug Rabson
4 .\"
5 .\" All rights reserved.
6 .\"
7 .\" This program is free software.
8 .\"
9 .\" Redistribution and use in source and binary forms, with or without
10 .\" modification, are permitted provided that the following conditions
11 .\" are met:
12 .\" 1. Redistributions of source code must retain the above copyright
13 .\" notice, this list of conditions and the following disclaimer.
14 .\" 2. Redistributions in binary form must reproduce the above copyright
15 .\" notice, this list of conditions and the following disclaimer in the
16 .\" documentation and/or other materials provided with the distribution.
17 .\"
18 .\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
19 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
20 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
21 .\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
22 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
23 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
24 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
25 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
26 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
27 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
28 .\"
29 .\" $FreeBSD$
30 .\"
31 .Dd June 13, 2008
32 .Dt TASKQUEUE 9
33 .Os
34 .Sh NAME
35 .Nm taskqueue
36 .Nd asynchronous task execution
37 .Sh SYNOPSIS
38 .In sys/param.h
39 .In sys/kernel.h
40 .In sys/malloc.h
41 .In sys/queue.h
42 .In sys/taskqueue.h
43 .Bd -literal
44 typedef void (*task_fn_t)(void *context, int pending);
46 typedef void (*taskqueue_enqueue_fn)(void *context);
48 struct task {
49 STAILQ_ENTRY(task) ta_link; /* link for queue */
50 u_short ta_pending; /* count times queued */
51 u_short ta_priority; /* priority of task in queue */
52 task_fn_t ta_func; /* task handler */
53 void *ta_context; /* argument for handler */
54 };
55 .Ed
56 .Ft struct taskqueue *
57 .Fn taskqueue_create "const char *name" "int mflags" "taskqueue_enqueue_fn enqueue" "void *context"
58 .Ft struct taskqueue *
59 .Fn taskqueue_create_fast "const char *name" "int mflags" "taskqueue_enqueue_fn enqueue" "void *context"
60 .Ft void
61 .Fn taskqueue_free "struct taskqueue *queue"
62 .Ft struct taskqueue *
63 .Fn taskqueue_find "const char *name"
64 .Ft int
65 .Fn taskqueue_enqueue "struct taskqueue *queue" "struct task *task"
66 .Ft int
67 .Fn taskqueue_enqueue_fast "struct taskqueue *queue" "struct task *task"
68 .Ft void
69 .Fn taskqueue_run "struct taskqueue *queue"
70 .Ft void
71 .Fn taskqueue_run_fast "struct taskqueue *queue"
72 .Ft void
73 .Fn taskqueue_drain "struct taskqueue *queue" "struct task *task"
74 .Fn TASK_INIT "struct task *task" "int priority" "task_fn_t *func" "void *context"
75 .Fn TASKQUEUE_DECLARE "name"
76 .Fn TASKQUEUE_DEFINE "name" "taskqueue_enqueue_fn enqueue" "void *context" "init"
77 .Fn TASKQUEUE_FAST_DEFINE "name" "taskqueue_enqueue_fn enqueue" "void *context" "init"
78 .Fn TASKQUEUE_DEFINE_THREAD "name"
79 .Fn TASKQUEUE_FAST_DEFINE_THREAD "name"
80 .Sh DESCRIPTION
81 These functions provide a simple interface for asynchronous execution
82 of code.
83 .Pp
84 The function
85 .Fn taskqueue_create
86 is used to create new queues.
87 The arguments to
88 .Fn taskqueue_create
89 include a name that should be unique,
90 a set of
91 .Xr malloc 9
92 flags that specify whether the call to
93 .Fn malloc
94 is allowed to sleep,
95 a function that is called from
96 .Fn taskqueue_enqueue
97 when a task is added to the queue,
98 and a pointer to the memory location where the identity of the
99 thread that services the queue is recorded.
100 .\" XXX The rest of the sentence gets lots in relation to the first part.
101 The function called from
102 .Fn taskqueue_enqueue
103 must arrange for the queue to be processed
104 (for instance by scheduling a software interrupt or waking a kernel
105 thread).
106 The memory location where the thread identity is recorded is used
107 to signal the service thread(s) to terminate--when this value is set to
108 zero and the thread is signaled it will terminate.
109 If the queue is intended for use in fast interrupt handlers
110 .Fn taskqueue_create_fast
111 should be used in place of
112 .Fn taskqueue_create .
113 .Pp
114 The function
115 .Fn taskqueue_free
116 should be used to remove the queue from the global list of queues
117 and free the memory used by the queue.
118 Any tasks that are on the queue will be executed at this time after
119 which the thread servicing the queue will be signaled that it should exit.
120 .Pp
121 The system maintains a list of all queues which can be searched using
122 .Fn taskqueue_find .
123 The first queue whose name matches is returned, otherwise
124 .Dv NULL .
125 .Pp
126 To add a task to the list of tasks queued on a taskqueue, call
127 .Fn taskqueue_enqueue
128 with pointers to the queue and task.
129 If the task's
130 .Va ta_pending
131 field is non-zero,
132 then it is simply incremented to reflect the number of times the task
133 was enqueued.
134 Otherwise,
135 the task is added to the list before the first task which has a lower
136 .Va ta_priority
137 value or at the end of the list if no tasks have a lower priority.
138 Enqueueing a task does not perform any memory allocation which makes
139 it suitable for calling from an interrupt handler.
140 This function will return
141 .Er EPIPE
142 if the queue is being freed.
143 .Pp
144 The function
145 .Fn taskqueue_enqueue_fast
146 should be used in place of
147 .Fn taskqueue_enqueue
148 when the enqueuing must happen from a fast interrupt handler.
149 This method uses spin locks to avoid the possibility of sleeping in the fast
150 interrupt context.
151 .Pp
152 To execute all the tasks on a queue,
153 call
154 .Fn taskqueue_run
155 or
156 .Fn taskqueue_run_fast
157 depending on the flavour of the queue.
158 When a task is executed,
159 first it is removed from the queue,
160 the value of
161 .Va ta_pending
162 is recorded and then the field is zeroed.
163 The function
164 .Va ta_func
165 from the task structure is called with the value of the field
166 .Va ta_context
167 as its first argument
168 and the value of
169 .Va ta_pending
170 as its second argument.
171 After the function
172 .Va ta_func
173 returns,
174 .Xr wakeup 9
175 is called on the task pointer passed to
176 .Fn taskqueue_enqueue .
177 .Pp
178 The
179 .Fn taskqueue_drain
180 function is used to wait for the task to finish.
181 There is no guarantee that the task will not be
182 enqueued after call to
183 .Fn taskqueue_drain .
184 .Pp
185 A convenience macro,
186 .Fn TASK_INIT "task" "priority" "func" "context"
187 is provided to initialise a
188 .Va task
189 structure.
190 The values of
191 .Va priority ,
192 .Va func ,
193 and
194 .Va context
195 are simply copied into the task structure fields and the
196 .Va ta_pending
197 field is cleared.
198 .Pp
199 Five macros
200 .Fn TASKQUEUE_DECLARE "name" ,
201 .Fn TASKQUEUE_DEFINE "name" "enqueue" "context" "init" ,
202 .Fn TASKQUEUE_FAST_DEFINE "name" "enqueue" "context" "init" ,
203 and
204 .Fn TASKQUEUE_DEFINE_THREAD "name"
205 .Fn TASKQUEUE_FAST_DEFINE_THREAD "name"
206 are used to declare a reference to a global queue, to define the
207 implementation of the queue, and declare a queue that uses its own thread.
208 The
209 .Fn TASKQUEUE_DEFINE
210 macro arranges to call
211 .Fn taskqueue_create
212 with the values of its
213 .Va name ,
214 .Va enqueue
215 and
216 .Va context
217 arguments during system initialisation.
218 After calling
219 .Fn taskqueue_create ,
220 the
221 .Va init
222 argument to the macro is executed as a C statement,
223 allowing any further initialisation to be performed
224 (such as registering an interrupt handler etc.)
225 .Pp
226 The
227 .Fn TASKQUEUE_DEFINE_THREAD
228 macro defines a new taskqueue with its own kernel thread to serve tasks.
229 The variable
230 .Vt struct taskqueue *taskqueue_name
231 is used to enqueue tasks onto the queue.
232 .Pp
233 .Fn TASKQUEUE_FAST_DEFINE
234 and
235 .Fn TASKQUEUE_FAST_DEFINE_THREAD
236 act just like
237 .Fn TASKQUEUE_DEFINE
238 and
239 .Fn TASKQUEUE_DEFINE_THREAD
240 respectively but taskqueue is created with
241 .Fn taskqueue_create_fast .
242 .Ss Predefined Task Queues
243 The system provides four global taskqueues,
244 .Va taskqueue_fast ,
245 .Va taskqueue_swi ,
246 .Va taskqueue_swi_giant ,
247 and
248 .Va taskqueue_thread .
249 The
250 .Va taskqueue_fast
251 queue is for swi handlers dispatched from fast interrupt handlers,
252 where sleep mutexes cannot be used.
253 The swi taskqueues are run via a software interrupt mechanism.
254 The
255 .Va taskqueue_swi
256 queue runs without the protection of the
257 .Va Giant
258 kernel lock, and the
259 .Va taskqueue_swi_giant
260 queue runs with the protection of the
261 .Va Giant
262 kernel lock.
263 The thread taskqueue
264 .Va taskqueue_thread
265 runs in a kernel thread context, and tasks run from this thread do
266 not run under the
267 .Va Giant
268 kernel lock.
269 If the caller wants to run under
270 .Va Giant ,
271 he should explicitly acquire and release
272 .Va Giant
273 in his taskqueue handler routine.
274 .Pp
275 To use these queues,
276 call
277 .Fn taskqueue_enqueue
278 with the value of the global taskqueue variable for the queue you wish to
279 use
280 .Va ( taskqueue_swi ,
281 .Va taskqueue_swi_giant ,
282 or
283 .Va taskqueue_thread ) .
284 Use
285 .Fn taskqueue_enqueue_fast
286 for the global taskqueue variable
287 .Va taskqueue_fast .
288 .Pp
289 The software interrupt queues can be used,
290 for instance, for implementing interrupt handlers which must perform a
291 significant amount of processing in the handler.
292 The hardware interrupt handler would perform minimal processing of the
293 interrupt and then enqueue a task to finish the work.
294 This reduces to a minimum
295 the amount of time spent with interrupts disabled.
296 .Pp
297 The thread queue can be used, for instance, by interrupt level routines
298 that need to call kernel functions that do things that can only be done
299 from a thread context.
300 (e.g., call malloc with the M_WAITOK flag.)
301 .Pp
302 Note that tasks queued on shared taskqueues such as
303 .Va taskqueue_swi
304 may be delayed an indeterminate amount of time before execution.
305 If queueing delays cannot be tolerated then a private taskqueue should
306 be created with a dedicated processing thread.
307 .Sh SEE ALSO
308 .Xr ithread 9 ,
309 .Xr kthread 9 ,
310 .Xr swi 9
311 .Sh HISTORY
312 This interface first appeared in
313 .Fx 5.0 .
314 There is a similar facility called tqueue in the Linux kernel.
315 .Sh AUTHORS
316 This manual page was written by
317 .An Doug Rabson .