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 $
29 .\" $DragonFly: src/share/man/man9/taskqueue.9,v 1.2 2007/11/07 21:38:00 swildner Exp $
35 .Nm taskqueue_create ,
38 .Nm taskqueue_enqueue ,
41 .Nm TASKQUEUE_DECLARE ,
43 .Nd asynchronous task execution
51 typedef void (*task_fn_t)(void *context, int pending);
53 typedef void (*taskqueue_enqueue_fn)(void *context);
56 STAILQ_ENTRY(task) ta_link; /* link for queue */
57 int ta_pending; /* count times queued */
58 int ta_priority; /* priority of task in queue */
59 task_fn_t ta_func; /* task handler */
60 void *ta_context; /* argument for handler */
63 .Ft struct taskqueue *
64 .Fn taskqueue_create "const char *name" "int mflags" "taskqueue_enqueue_fn enqueue" "void *context"
66 .Fn taskqueue_free "struct taskqueue *queue"
67 .Ft struct taskqueue *
68 .Fn taskqueue_find "const char *name"
70 .Fn taskqueue_enqueue "struct taskqueue *queue" "struct task *task"
72 .Fn taskqueue_run "struct taskqueue *queue"
74 .Fn taskqueue_drain "struct taskqueue *queue" "struct task *task"
76 .Fn taskqueue_block "struct taskqueue *queue"
78 .Fn taskqueue_unblock "struct taskqueue *queue"
80 .Fn taskqueue_start_threads "struct taskqueue **tqp" "int count" "int pri" "int ncpu" "const char *fmt" "..."
81 .Fn TASK_INIT "struct task *task" "int priority" "task_fn_t *func" "void *context"
82 .Fn TASKQUEUE_DECLARE "name"
83 .Fn TASKQUEUE_DEFINE "name" "taskqueue_enqueue_fn enqueue" "void *context" "init"
85 These functions provide a simple interface for asynchronous execution
90 is used to create new queues.
93 include a name that should be unique,
96 flags that specify whether the call to
99 and a function which is called from
100 .Fn taskqueue_enqueue
101 when a task is added to the queue
102 .\" XXX The rest of the sentence gets lots in relation to the first part.
103 to allow the queue to arrange to be run later
104 (for instance by scheduling a software interrupt or waking a kernel
109 should be used to remove the queue from the global list of queues
110 and free the memory used by the queue.
111 Any tasks that are on the queue will be executed at this time.
113 The system maintains a list of all queues which can be searched using
115 The first queue whose name matches is returned, otherwise
118 To add a task to the list of tasks queued on a taskqueue, call
119 .Fn taskqueue_enqueue
120 with pointers to the queue and task.
124 then it is simply incremented to reflect the number of times the task
127 the task is added to the list before the first task which has a lower
129 value or at the end of the list if no tasks have a lower priority.
130 Enqueueing a task does not perform any memory allocation which makes
131 it suitable for calling from an interrupt handler.
132 This function will return
134 if the queue is being freed.
136 To execute all the tasks on a queue,
139 When a task is executed,
140 first it is removed from the queue,
143 is recorded and then the field is zeroed.
146 from the task structure is called with the value of the field
148 as its first argument
151 as its second argument.
155 function is used to wait for the task to finish.
156 There is no guarantee that the task will not be
157 enqueued after call to
158 .Fn taskqueue_drain .
162 function is used to block a taskqueue. When a taskqueue
163 is blocked, calls to enqueue will still enqueue tasks but
164 they will not be run until the taskqueue is unblocked by
166 .Fn taskqueue_unblock .
169 .Fn taskqueue_start_threads
170 function is used to create and start
172 dedicated threads for the taskqueue specified by
174 These threads will be created with the priority specified by
176 and the name given by
178 with _N appended to it, where N is the number of the thread.
185 threads will be allocated to a different
186 CPU among all available CPUs in a round robin fashion.
187 The taskqueue specified by
189 must be created previously by calling
194 .Fa taskqueue_thread_enqueue .
198 is provided to initialise a
206 are simply copied into the task structure fields and the
211 .Fn TASKQUEUE_DECLARE
214 are used to declare a reference to a global queue,
215 and to define the implementation of the queue.
218 macro arranges to call
220 with the values of its
225 arguments during system initialisation.
227 .Fn taskqueue_create ,
230 argument to the macro is executed as a C statement,
231 allowing any further initialisation to be performed
232 (such as registering an interrupt handler etc.)
234 The system provides two global taskqueues,
236 .Va taskqueue_swi_mp ,
237 which are run via a software interrupt mechanism.
238 To use these queues, call
239 .Fn taskqueue_enqueue
240 with the value of the global variable
242 .Va taskqueue_swi_mp .
246 acquires the mplock for its tasks,
248 is intended for mpsafe tasks and no mplock will be acquired for them.
249 These queues can be used,
250 for instance, for implementing interrupt handlers which must perform a
251 significant amount of processing in the handler.
252 The hardware interrupt handler would perform minimal processing of the
253 interrupt and then enqueue a task to finish the work.
254 This reduces to a minimum
255 the amount of time spent with interrupts disabled.
261 This interface first appeared in
263 There is a similar facility called tqueue in the Linux kernel.
265 This manual page was written by