3 .\" Copyright (c) 2000 Doug Rabson
5 .\" All rights reserved.
7 .\" This program is free software.
9 .\" Redistribution and use in source and binary forms, with or without
10 .\" modification, are permitted provided that the following conditions
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.
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.
36 .Nd asynchronous task execution
44 typedef void (*task_fn_t)(void *context, int pending);
46 typedef void (*taskqueue_enqueue_fn)(void *context);
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 */
56 enum taskqueue_callback_type {
57 TASKQUEUE_CALLBACK_TYPE_INIT,
58 TASKQUEUE_CALLBACK_TYPE_SHUTDOWN,
61 typedef void (*taskqueue_callback_fn)(void *context);
65 .Ft struct taskqueue *
66 .Fn taskqueue_create "const char *name" "int mflags" "taskqueue_enqueue_fn enqueue" "void *context"
67 .Ft struct taskqueue *
68 .Fn taskqueue_create_fast "const char *name" "int mflags" "taskqueue_enqueue_fn enqueue" "void *context"
70 .Fn taskqueue_start_threads "struct taskqueue **tqp" "int count" "int pri" "const char *name" "..."
72 .Fn taskqueue_set_callback "struct taskqueue *queue" "enum taskqueue_callback_type cb_type" "taskqueue_callback_fn callback" "void *context"
74 .Fn taskqueue_free "struct taskqueue *queue"
76 .Fn taskqueue_enqueue "struct taskqueue *queue" "struct task *task"
78 .Fn taskqueue_enqueue_fast "struct taskqueue *queue" "struct task *task"
80 .Fn taskqueue_enqueue_timeout "struct taskqueue *queue" "struct timeout_task *timeout_task" "int ticks"
82 .Fn taskqueue_cancel "struct taskqueue *queue" "struct task *task" "u_int *pendp"
84 .Fn taskqueue_cancel_timeout "struct taskqueue *queue" "struct timeout_task *timeout_task" "u_int *pendp"
86 .Fn taskqueue_drain "struct taskqueue *queue" "struct task *task"
88 .Fn taskqueue_drain_timeout "struct taskqueue *queue" "struct timeout_task *timeout_task"
90 .Fn taskqueue_drain_all "struct taskqueue *queue"
92 .Fn taskqueue_block "struct taskqueue *queue"
94 .Fn taskqueue_unblock "struct taskqueue *queue"
96 .Fn taskqueue_member "struct taskqueue *queue" "struct thread *td"
98 .Fn taskqueue_run "struct taskqueue *queue"
99 .Fn TASK_INIT "struct task *task" "int priority" "task_fn_t func" "void *context"
100 .Fn TASK_INITIALIZER "int priority" "task_fn_t func" "void *context"
101 .Fn TASKQUEUE_DECLARE "name"
102 .Fn TASKQUEUE_DEFINE "name" "taskqueue_enqueue_fn enqueue" "void *context" "init"
103 .Fn TASKQUEUE_FAST_DEFINE "name" "taskqueue_enqueue_fn enqueue" "void *context" "init"
104 .Fn TASKQUEUE_DEFINE_THREAD "name"
105 .Fn TASKQUEUE_FAST_DEFINE_THREAD "name"
106 .Fn TIMEOUT_TASK_INIT "struct taskqueue *queue" "struct timeout_task *timeout_task" "int priority" "task_fn_t func" "void *context"
108 These functions provide a simple interface for asynchronous execution
113 is used to create new queues.
116 include a name that should be unique,
119 flags that specify whether the call to
122 a function that is called from
123 .Fn taskqueue_enqueue
124 when a task is added to the queue,
125 and a pointer to the memory location where the identity of the
126 thread that services the queue is recorded.
127 .\" XXX The rest of the sentence gets lots in relation to the first part.
128 The function called from
129 .Fn taskqueue_enqueue
130 must arrange for the queue to be processed
131 (for instance by scheduling a software interrupt or waking a kernel
133 The memory location where the thread identity is recorded is used
134 to signal the service thread(s) to terminate--when this value is set to
135 zero and the thread is signaled it will terminate.
136 If the queue is intended for use in fast interrupt handlers
137 .Fn taskqueue_create_fast
138 should be used in place of
139 .Fn taskqueue_create .
143 should be used to free the memory used by the queue.
144 Any tasks that are on the queue will be executed at this time after
145 which the thread servicing the queue will be signaled that it should exit.
147 Once a taskqueue has been created, its threads should be started using
148 .Fn taskqueue_start_threads .
149 Callbacks may optionally be registered using
150 .Fn taskqueue_set_callback .
151 Currently, callbacks may be registered for the following purposes:
152 .Bl -tag -width TASKQUEUE_CALLBACK_TYPE_SHUTDOWN
153 .It Dv TASKQUEUE_CALLBACK_TYPE_INIT
154 This callback is called by every thread in the taskqueue, before it executes
156 This callback must be set before the taskqueue's threads are started.
157 .It Dv TASKQUEUE_CALLBACK_TYPE_SHUTDOWN
158 This callback is called by every thread in the taskqueue, after it executes
160 This callback will always be called before the taskqueue structure is
164 To add a task to the list of tasks queued on a taskqueue, call
165 .Fn taskqueue_enqueue
166 with pointers to the queue and task.
170 then it is simply incremented to reflect the number of times the task
171 was enqueued, up to a cap of USHRT_MAX.
173 the task is added to the list before the first task which has a lower
175 value or at the end of the list if no tasks have a lower priority.
176 Enqueueing a task does not perform any memory allocation which makes
177 it suitable for calling from an interrupt handler.
178 This function will return
180 if the queue is being freed.
183 .Fn taskqueue_enqueue_fast
184 should be used in place of
185 .Fn taskqueue_enqueue
186 when the enqueuing must happen from a fast interrupt handler.
187 This method uses spin locks to avoid the possibility of sleeping in the fast
190 When a task is executed,
191 first it is removed from the queue,
194 is recorded and then the field is zeroed.
197 from the task structure is called with the value of the field
199 as its first argument
202 as its second argument.
207 is called on the task pointer passed to
208 .Fn taskqueue_enqueue .
211 .Fn taskqueue_enqueue_timeout
212 is used to schedule the enqueue after the specified amount of
214 Only non-fast task queues can be used for
219 argument is negative, the already scheduled enqueueing is not re-scheduled.
220 Otherwise, the task is scheduled for enqueueing in the future,
221 after the absolute value of
227 function is used to cancel a task.
230 count is cleared, and the old value returned in the reference
235 If the task is currently running,
237 is returned, otherwise 0.
238 To implement a blocking
240 that waits for a running task to finish, it could look like:
241 .Bd -literal -offset indent
242 while (taskqueue_cancel(tq, task, NULL) != 0)
243 taskqueue_drain(tq, task);
247 .Fn taskqueue_drain ,
248 the caller is responsible for ensuring that the task is not re-enqueued
249 after being canceled.
252 .Fn taskqueue_cancel_timeout
253 function is used to cancel the scheduled task execution.
257 function is used to wait for the task to finish, and
259 .Fn taskqueue_drain_timeout
260 function is used to wait for the scheduled task to finish.
261 There is no guarantee that the task will not be
262 enqueued after call to
263 .Fn taskqueue_drain .
264 If the caller wants to put the task into a known state,
267 the caller should use out-of-band means to ensure that the task
268 would not be enqueued.
269 For example, if the task is enqueued by an interrupt filter, then
270 the interrupt could be disabled.
273 .Fn taskqueue_drain_all
274 function is used to wait for all pending and running tasks that
275 are enqueued on the taskqueue to finish.
276 The caller must arrange that the tasks are not re-enqueued.
278 .Fn taskqueue_drain_all
279 currently does not handle tasks with delayed enqueueing.
283 function blocks the taskqueue.
284 It prevents any enqueued but not running tasks from being executed.
286 .Fn taskqueue_enqueue
287 will enqueue tasks, but the tasks will not be run until
288 .Fn taskqueue_unblock
292 does not wait for any currently running tasks to finish.
295 does not provide a guarantee that
299 returns, but it does provide a guarantee that
301 will not be called again
303 .Fn taskqueue_unblock
305 If the caller requires a guarantee that
307 is not running, then this must be arranged by the caller.
310 is called on a task that is enqueued on a taskqueue that is blocked by
311 .Fn taskqueue_block ,
314 can not return until the taskqueue is unblocked.
315 This can result in a deadlock if the thread blocked in
317 is the thread that is supposed to call
318 .Fn taskqueue_unblock .
323 is discouraged, because the state of the task can not be known in advance.
324 The same caveat applies to
325 .Fn taskqueue_drain_all .
328 .Fn taskqueue_unblock
329 function unblocks the previously blocked taskqueue.
330 All enqueued tasks can be run after this call.
338 is part of the given taskqueue
346 function will run all pending tasks in the specified
348 Normally this function is only used internally.
351 .Fn TASK_INIT "task" "priority" "func" "context"
352 is provided to initialise a
357 macro generates an initializer for a task structure.
359 .Fn TIMEOUT_TASK_INIT "queue" "timeout_task" "priority" "func" "context"
368 are simply copied into the task structure fields and the
373 .Fn TASKQUEUE_DECLARE "name" ,
374 .Fn TASKQUEUE_DEFINE "name" "enqueue" "context" "init" ,
375 .Fn TASKQUEUE_FAST_DEFINE "name" "enqueue" "context" "init" ,
377 .Fn TASKQUEUE_DEFINE_THREAD "name"
378 .Fn TASKQUEUE_FAST_DEFINE_THREAD "name"
379 are used to declare a reference to a global queue, to define the
380 implementation of the queue, and declare a queue that uses its own thread.
383 macro arranges to call
385 with the values of its
390 arguments during system initialisation.
392 .Fn taskqueue_create ,
395 argument to the macro is executed as a C statement,
396 allowing any further initialisation to be performed
397 (such as registering an interrupt handler etc.)
400 .Fn TASKQUEUE_DEFINE_THREAD
401 macro defines a new taskqueue with its own kernel thread to serve tasks.
403 .Vt struct taskqueue *taskqueue_name
404 is used to enqueue tasks onto the queue.
406 .Fn TASKQUEUE_FAST_DEFINE
408 .Fn TASKQUEUE_FAST_DEFINE_THREAD
412 .Fn TASKQUEUE_DEFINE_THREAD
413 respectively but taskqueue is created with
414 .Fn taskqueue_create_fast .
415 .Ss Predefined Task Queues
416 The system provides four global taskqueues,
419 .Va taskqueue_swi_giant ,
421 .Va taskqueue_thread .
424 queue is for swi handlers dispatched from fast interrupt handlers,
425 where sleep mutexes cannot be used.
426 The swi taskqueues are run via a software interrupt mechanism.
429 queue runs without the protection of the
432 .Va taskqueue_swi_giant
433 queue runs with the protection of the
438 runs in a kernel thread context, and tasks run from this thread do
442 If the caller wants to run under
444 he should explicitly acquire and release
446 in his taskqueue handler routine.
450 .Fn taskqueue_enqueue
451 with the value of the global taskqueue variable for the queue you wish to
453 .Va ( taskqueue_swi ,
454 .Va taskqueue_swi_giant ,
456 .Va taskqueue_thread ) .
458 .Fn taskqueue_enqueue_fast
459 for the global taskqueue variable
462 The software interrupt queues can be used,
463 for instance, for implementing interrupt handlers which must perform a
464 significant amount of processing in the handler.
465 The hardware interrupt handler would perform minimal processing of the
466 interrupt and then enqueue a task to finish the work.
467 This reduces to a minimum
468 the amount of time spent with interrupts disabled.
470 The thread queue can be used, for instance, by interrupt level routines
471 that need to call kernel functions that do things that can only be done
472 from a thread context.
473 (e.g., call malloc with the M_WAITOK flag.)
475 Note that tasks queued on shared taskqueues such as
477 may be delayed an indeterminate amount of time before execution.
478 If queueing delays cannot be tolerated then a private taskqueue should
479 be created with a dedicated processing thread.
485 This interface first appeared in
487 There is a similar facility called work_queue in the Linux kernel.
489 This manual page was written by