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 .Fo taskqueue_start_threads_pinned
73 .Fa "struct taskqueue **tqp" "int count" "int pri" "int cpu_id"
74 .Fa "const char *name" "..."
77 .Fn taskqueue_set_callback "struct taskqueue *queue" "enum taskqueue_callback_type cb_type" "taskqueue_callback_fn callback" "void *context"
79 .Fn taskqueue_free "struct taskqueue *queue"
81 .Fn taskqueue_enqueue "struct taskqueue *queue" "struct task *task"
83 .Fn taskqueue_enqueue_timeout "struct taskqueue *queue" "struct timeout_task *timeout_task" "int ticks"
85 .Fn taskqueue_enqueue_timeout_sbt "struct taskqueue *queue" "struct timeout_task *timeout_task" "sbintime_t sbt" "sbintime_t pr" "int flags"
87 .Fn taskqueue_cancel "struct taskqueue *queue" "struct task *task" "u_int *pendp"
89 .Fn taskqueue_cancel_timeout "struct taskqueue *queue" "struct timeout_task *timeout_task" "u_int *pendp"
91 .Fn taskqueue_drain "struct taskqueue *queue" "struct task *task"
93 .Fn taskqueue_drain_timeout "struct taskqueue *queue" "struct timeout_task *timeout_task"
95 .Fn taskqueue_drain_all "struct taskqueue *queue"
97 .Fn taskqueue_block "struct taskqueue *queue"
99 .Fn taskqueue_unblock "struct taskqueue *queue"
101 .Fn taskqueue_member "struct taskqueue *queue" "struct thread *td"
103 .Fn taskqueue_run "struct taskqueue *queue"
104 .Fn TASK_INIT "struct task *task" "int priority" "task_fn_t func" "void *context"
105 .Fn TASK_INITIALIZER "int priority" "task_fn_t func" "void *context"
106 .Fn TASKQUEUE_DECLARE "name"
107 .Fn TASKQUEUE_DEFINE "name" "taskqueue_enqueue_fn enqueue" "void *context" "init"
108 .Fn TASKQUEUE_FAST_DEFINE "name" "taskqueue_enqueue_fn enqueue" "void *context" "init"
109 .Fn TASKQUEUE_DEFINE_THREAD "name"
110 .Fn TASKQUEUE_FAST_DEFINE_THREAD "name"
111 .Fn TIMEOUT_TASK_INIT "struct taskqueue *queue" "struct timeout_task *timeout_task" "int priority" "task_fn_t func" "void *context"
113 These functions provide a simple interface for asynchronous execution
118 is used to create new queues.
121 include a name that should be unique,
124 flags that specify whether the call to
127 a function that is called from
128 .Fn taskqueue_enqueue
129 when a task is added to the queue,
130 and a pointer to the memory location where the identity of the
131 thread that services the queue is recorded.
132 .\" XXX The rest of the sentence gets lots in relation to the first part.
133 The function called from
134 .Fn taskqueue_enqueue
135 must arrange for the queue to be processed
136 (for instance by scheduling a software interrupt or waking a kernel
138 The memory location where the thread identity is recorded is used
139 to signal the service thread(s) to terminate--when this value is set to
140 zero and the thread is signaled it will terminate.
141 If the queue is intended for use in fast interrupt handlers
142 .Fn taskqueue_create_fast
143 should be used in place of
144 .Fn taskqueue_create .
148 should be used to free the memory used by the queue.
149 Any tasks that are on the queue will be executed at this time after
150 which the thread servicing the queue will be signaled that it should exit.
152 Once a taskqueue has been created, its threads should be started using
153 .Fn taskqueue_start_threads
155 .Fn taskqueue_start_threads_pinned .
156 .Fn taskqueue_start_threads_pinned
159 argument which will cause the threads which are started for the taskqueue
160 to be pinned to run on the given CPU.
161 Callbacks may optionally be registered using
162 .Fn taskqueue_set_callback .
163 Currently, callbacks may be registered for the following purposes:
164 .Bl -tag -width TASKQUEUE_CALLBACK_TYPE_SHUTDOWN
165 .It Dv TASKQUEUE_CALLBACK_TYPE_INIT
166 This callback is called by every thread in the taskqueue, before it executes
168 This callback must be set before the taskqueue's threads are started.
169 .It Dv TASKQUEUE_CALLBACK_TYPE_SHUTDOWN
170 This callback is called by every thread in the taskqueue, after it executes
172 This callback will always be called before the taskqueue structure is
176 To add a task to the list of tasks queued on a taskqueue, call
177 .Fn taskqueue_enqueue
178 with pointers to the queue and task.
182 then it is simply incremented to reflect the number of times the task
183 was enqueued, up to a cap of USHRT_MAX.
185 the task is added to the list before the first task which has a lower
187 value or at the end of the list if no tasks have a lower priority.
188 Enqueueing a task does not perform any memory allocation which makes
189 it suitable for calling from an interrupt handler.
190 This function will return
192 if the queue is being freed.
194 When a task is executed,
195 first it is removed from the queue,
198 is recorded and then the field is zeroed.
201 from the task structure is called with the value of the field
203 as its first argument
206 as its second argument.
211 is called on the task pointer passed to
212 .Fn taskqueue_enqueue .
215 .Fn taskqueue_enqueue_timeout
216 function is used to schedule the enqueue after the specified number of
219 .Fn taskqueue_enqueue_timeout_sbt
220 function provides finer control over the scheduling based on
227 Only non-fast task queues can be used for
232 argument is negative, the already scheduled enqueueing is not re-scheduled.
233 Otherwise, the task is scheduled for enqueueing in the future,
234 after the absolute value of
237 This function returns -1 if the task is being drained.
238 Otherwise, the number of pending calls is returned.
242 function is used to cancel a task.
245 count is cleared, and the old value returned in the reference
250 If the task is currently running,
252 is returned, otherwise 0.
253 To implement a blocking
255 that waits for a running task to finish, it could look like:
256 .Bd -literal -offset indent
257 while (taskqueue_cancel(tq, task, NULL) != 0)
258 taskqueue_drain(tq, task);
262 .Fn taskqueue_drain ,
263 the caller is responsible for ensuring that the task is not re-enqueued
264 after being canceled.
267 .Fn taskqueue_cancel_timeout
268 function is used to cancel the scheduled task execution.
272 function is used to wait for the task to finish, and
274 .Fn taskqueue_drain_timeout
275 function is used to wait for the scheduled task to finish.
276 There is no guarantee that the task will not be
277 enqueued after call to
278 .Fn taskqueue_drain .
279 If the caller wants to put the task into a known state,
282 the caller should use out-of-band means to ensure that the task
283 would not be enqueued.
284 For example, if the task is enqueued by an interrupt filter, then
285 the interrupt could be disabled.
288 .Fn taskqueue_drain_all
289 function is used to wait for all pending and running tasks that
290 are enqueued on the taskqueue to finish.
291 Tasks posted to the taskqueue after
292 .Fn taskqueue_drain_all
294 including pending enqueues scheduled by a previous call to
295 .Fn taskqueue_enqueue_timeout ,
296 do not extend the wait time of
297 .Fn taskqueue_drain_all
298 and may complete after
299 .Fn taskqueue_drain_all
304 function blocks the taskqueue.
305 It prevents any enqueued but not running tasks from being executed.
307 .Fn taskqueue_enqueue
308 will enqueue tasks, but the tasks will not be run until
309 .Fn taskqueue_unblock
313 does not wait for any currently running tasks to finish.
316 does not provide a guarantee that
320 returns, but it does provide a guarantee that
322 will not be called again
324 .Fn taskqueue_unblock
326 If the caller requires a guarantee that
328 is not running, then this must be arranged by the caller.
331 is called on a task that is enqueued on a taskqueue that is blocked by
332 .Fn taskqueue_block ,
335 can not return until the taskqueue is unblocked.
336 This can result in a deadlock if the thread blocked in
338 is the thread that is supposed to call
339 .Fn taskqueue_unblock .
344 is discouraged, because the state of the task can not be known in advance.
345 The same caveat applies to
346 .Fn taskqueue_drain_all .
349 .Fn taskqueue_unblock
350 function unblocks the previously blocked taskqueue.
351 All enqueued tasks can be run after this call.
359 is part of the given taskqueue
367 function will run all pending tasks in the specified
369 Normally this function is only used internally.
372 .Fn TASK_INIT "task" "priority" "func" "context"
373 is provided to initialise a
378 macro generates an initializer for a task structure.
380 .Fn TIMEOUT_TASK_INIT "queue" "timeout_task" "priority" "func" "context"
389 are simply copied into the task structure fields and the
394 .Fn TASKQUEUE_DECLARE "name" ,
395 .Fn TASKQUEUE_DEFINE "name" "enqueue" "context" "init" ,
396 .Fn TASKQUEUE_FAST_DEFINE "name" "enqueue" "context" "init" ,
398 .Fn TASKQUEUE_DEFINE_THREAD "name"
399 .Fn TASKQUEUE_FAST_DEFINE_THREAD "name"
400 are used to declare a reference to a global queue, to define the
401 implementation of the queue, and declare a queue that uses its own thread.
404 macro arranges to call
406 with the values of its
411 arguments during system initialisation.
413 .Fn taskqueue_create ,
416 argument to the macro is executed as a C statement,
417 allowing any further initialisation to be performed
418 (such as registering an interrupt handler, etc.).
421 .Fn TASKQUEUE_DEFINE_THREAD
422 macro defines a new taskqueue with its own kernel thread to serve tasks.
424 .Vt struct taskqueue *taskqueue_name
425 is used to enqueue tasks onto the queue.
427 .Fn TASKQUEUE_FAST_DEFINE
429 .Fn TASKQUEUE_FAST_DEFINE_THREAD
433 .Fn TASKQUEUE_DEFINE_THREAD
434 respectively but taskqueue is created with
435 .Fn taskqueue_create_fast .
436 .Ss Predefined Task Queues
437 The system provides four global taskqueues,
440 .Va taskqueue_swi_giant ,
442 .Va taskqueue_thread .
445 queue is for swi handlers dispatched from fast interrupt handlers,
446 where sleep mutexes cannot be used.
447 The swi taskqueues are run via a software interrupt mechanism.
450 queue runs without the protection of the
453 .Va taskqueue_swi_giant
454 queue runs with the protection of the
459 runs in a kernel thread context, and tasks run from this thread do
463 If the caller wants to run under
465 he should explicitly acquire and release
467 in his taskqueue handler routine.
471 .Fn taskqueue_enqueue
472 with the value of the global taskqueue variable for the queue you wish to
475 The software interrupt queues can be used,
476 for instance, for implementing interrupt handlers which must perform a
477 significant amount of processing in the handler.
478 The hardware interrupt handler would perform minimal processing of the
479 interrupt and then enqueue a task to finish the work.
480 This reduces to a minimum
481 the amount of time spent with interrupts disabled.
483 The thread queue can be used, for instance, by interrupt level routines
484 that need to call kernel functions that do things that can only be done
485 from a thread context.
486 (e.g., call malloc with the M_WAITOK flag.)
488 Note that tasks queued on shared taskqueues such as
490 may be delayed an indeterminate amount of time before execution.
491 If queueing delays cannot be tolerated then a private taskqueue should
492 be created with a dedicated processing thread.
499 This interface first appeared in
501 There is a similar facility called work_queue in the Linux kernel.
503 This manual page was written by