2 .\" Copyright (c) 2000 Doug Rabson
4 .\" All rights reserved.
6 .\" This program is free software.
8 .\" Redistribution and use in source and binary forms, with or without
9 .\" modification, are permitted provided that the following conditions
11 .\" 1. Redistributions of source code must retain the above copyright
12 .\" notice, this list of conditions and the following disclaimer.
13 .\" 2. Redistributions in binary form must reproduce the above copyright
14 .\" notice, this list of conditions and the following disclaimer in the
15 .\" documentation and/or other materials provided with the distribution.
17 .\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
18 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
19 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
20 .\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
21 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
22 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
23 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
24 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
25 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
26 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
28 .\" $FreeBSD: src/share/man/man9/taskqueue.9,v 1.21 2007/07/09 06:24:10 jmg Exp $
35 .Nm taskqueue_create ,
37 .Nm taskqueue_enqueue ,
41 .Nm taskqueue_start_threads ,
42 .Nm taskqueue_unblock ,
44 .Nm TASKQUEUE_DECLARE ,
46 .Nd asynchronous task execution
54 typedef void (*task_fn_t)(void *context, int pending);
56 typedef void (*taskqueue_enqueue_fn)(void *context);
59 STAILQ_ENTRY(task) ta_link; /* link for queue */
60 int ta_pending; /* count times queued */
61 int ta_priority; /* priority of task in queue */
62 task_fn_t ta_func; /* task handler */
63 void *ta_context; /* argument for handler */
66 .Ft struct taskqueue *
67 .Fn taskqueue_create "const char *name" "int mflags" "taskqueue_enqueue_fn enqueue" "void *context"
69 .Fn taskqueue_free "struct taskqueue *queue"
70 .Ft struct taskqueue *
71 .Fn taskqueue_find "const char *name"
73 .Fn taskqueue_enqueue "struct taskqueue *queue" "struct task *task"
75 .Fn taskqueue_run "struct taskqueue *queue"
77 .Fn taskqueue_drain "struct taskqueue *queue" "struct task *task"
79 .Fn taskqueue_block "struct taskqueue *queue"
81 .Fn taskqueue_unblock "struct taskqueue *queue"
83 .Fn taskqueue_start_threads "struct taskqueue **tqp" "int count" "int pri" "int ncpu" "const char *fmt" "..."
84 .Fn TASK_INIT "struct task *task" "int priority" "task_fn_t *func" "void *context"
85 .Fn TASKQUEUE_DECLARE "name"
86 .Fn TASKQUEUE_DEFINE "name" "taskqueue_enqueue_fn enqueue" "void *context" "init"
88 These functions provide a simple interface for asynchronous execution
93 is used to create new queues.
96 include a name that should be unique,
99 flags that specify whether the call to
102 and a function which is called from
103 .Fn taskqueue_enqueue
104 when a task is added to the queue
105 .\" XXX The rest of the sentence gets lots in relation to the first part.
106 to allow the queue to arrange to be run later
107 (for instance by scheduling a software interrupt or waking a kernel
112 should be used to remove the queue from the global list of queues
113 and free the memory used by the queue.
114 Any tasks that are on the queue will be executed at this time.
116 The system maintains a list of all queues which can be searched using
118 The first queue whose name matches is returned, otherwise
121 To add a task to the list of tasks queued on a taskqueue, call
122 .Fn taskqueue_enqueue
123 with pointers to the queue and task.
127 then it is simply incremented to reflect the number of times the task
130 the task is added to the list before the first task which has a lower
132 value or at the end of the list if no tasks have a lower priority.
133 Enqueueing a task does not perform any memory allocation which makes
134 it suitable for calling from an interrupt handler.
135 This function will return
137 if the queue is being freed.
139 To execute all the tasks on a queue,
142 When a task is executed,
143 first it is removed from the queue,
146 is recorded and then the field is zeroed.
149 from the task structure is called with the value of the field
151 as its first argument
154 as its second argument.
158 function is used to wait for the task to finish.
159 There is no guarantee that the task will not be
160 enqueued after call to
161 .Fn taskqueue_drain .
165 function is used to block a taskqueue.
166 When a taskqueue is blocked, calls to
167 .Fn taskqueue_enqueue
168 will still enqueue tasks but
169 they will not be run until the taskqueue is unblocked by calling
170 .Fn taskqueue_unblock .
173 .Fn taskqueue_start_threads
174 function is used to create and start
176 dedicated threads for the taskqueue specified by
178 These threads will be created with the priority specified by
180 and the name given by
182 with _N appended to it, where N is the number of the thread.
189 threads will be allocated to a different
190 CPU among all available CPUs in a round robin fashion.
191 The taskqueue specified by
193 must be created previously by calling
198 .Fa taskqueue_thread_enqueue .
202 is provided to initialise a
210 are simply copied into the task structure fields and the
215 .Fn TASKQUEUE_DECLARE
218 are used to declare a reference to a global queue,
219 and to define the implementation of the queue.
222 macro arranges to call
224 with the values of its
229 arguments during system initialisation.
231 .Fn taskqueue_create ,
234 argument to the macro is executed as a C statement,
235 allowing any further initialisation to be performed
236 (such as registering an interrupt handler etc.)
238 The system provides two global taskqueues,
241 .Va taskqueue_swi_mp ,
242 which are run via a software interrupt mechanism.
243 To use these queues, call
244 .Fn taskqueue_enqueue
245 with the value of the global variable
248 .Va taskqueue_swi_mp .
252 acquires the mplock for its tasks,
254 is intended for mpsafe tasks and no mplock will be acquired for them.
255 These queues can be used,
256 for instance, for implementing interrupt handlers which must perform a
257 significant amount of processing in the handler.
258 The hardware interrupt handler would perform minimal processing of the
259 interrupt and then enqueue a task to finish the work.
260 This reduces to a minimum
261 the amount of time spent with interrupts disabled.
267 This interface first appeared in
269 There is a similar facility called tqueue in the Linux kernel.
271 This manual page was written by