taskqueue.9 - Update to reflect tq changes
[dragonfly.git] / share / man / man9 / taskqueue.9
1 .\"
2 .\" Copyright (c) 2000 Doug Rabson
3 .\"
4 .\" All rights reserved.
5 .\"
6 .\" This program is free software.
7 .\"
8 .\" Redistribution and use in source and binary forms, with or without
9 .\" modification, are permitted provided that the following conditions
10 .\" are met:
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.
16 .\"
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.
27 .\"
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 $
30 .\"
31 .Dd August 10, 2007
32 .Dt TASKQUEUE 9
33 .Os
34 .Sh NAME
35 .Nm taskqueue_create ,
36 .Nm taskqueue_free ,
37 .Nm taskqueue_find ,
38 .Nm taskqueue_enqueue ,
39 .Nm taskqueue_run ,
40 .Nm TASK_INIT ,
41 .Nm TASKQUEUE_DECLARE ,
42 .Nm TASKQUEUE_DEFINE
43 .Nd asynchronous task execution
44 .Sh SYNOPSIS
45 .In sys/param.h
46 .In sys/kernel.h
47 .In sys/malloc.h
48 .In sys/queue.h
49 .In sys/taskqueue.h
50 .Bd -literal
51 typedef void (*task_fn_t)(void *context, int pending);
52
53 typedef void (*taskqueue_enqueue_fn)(void *context);
54
55 struct task {
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 */
61 };
62 .Ed
63 .Ft struct taskqueue *
64 .Fn taskqueue_create "const char *name" "int mflags" "taskqueue_enqueue_fn enqueue" "void *context"
65 .Ft void
66 .Fn taskqueue_free "struct taskqueue *queue"
67 .Ft struct taskqueue *
68 .Fn taskqueue_find "const char *name"
69 .Ft int
70 .Fn taskqueue_enqueue "struct taskqueue *queue" "struct task *task"
71 .Ft void
72 .Fn taskqueue_run "struct taskqueue *queue"
73 .Ft void
74 .Fn taskqueue_drain "struct taskqueue *queue" "struct task *task"
75 .Ft void
76 .Fn taskqueue_block "struct taskqueue *queue"
77 .Ft void
78 .Fn taskqueue_unblock "struct taskqueue *queue"
79 .Ft int
80 .Fn taskqueue_start_threads "struct taskqueue **tqp" "int count" "int pri" "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"
84 .Sh DESCRIPTION
85 These functions provide a simple interface for asynchronous execution
86 of code.
87 .Pp
88 The function
89 .Fn taskqueue_create
90 is used to create new queues.
91 The arguments to
92 .Fn taskqueue_create
93 include a name that should be unique,
94 a set of
95 .Xr kmalloc 9
96 flags that specify whether the call to
97 .Fn malloc
98 is allowed to sleep,
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
105 thread).
106 .Pp
107 The function
108 .Fn taskqueue_free
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.
112 .Pp
113 The system maintains a list of all queues which can be searched using
114 .Fn taskqueue_find .
115 The first queue whose name matches is returned, otherwise
116 .Dv NULL .
117 .Pp
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.
121 If the task's
122 .Fa ta_pending
123 field is non-zero,
124 then it is simply incremented to reflect the number of times the task
125 was enqueued.
126 Otherwise,
127 the task is added to the list before the first task which has a lower
128 .Fa ta_priority
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
133 .Er EPIPE
134 if the queue is being freed.
135 .Pp
136 To execute all the tasks on a queue,
137 call
138 .Fn taskqueue_run .
139 When a task is executed,
140 first it is removed from the queue,
141 the value of
142 .Fa ta_pending
143 is recorded and then the field is zeroed.
144 The function
145 .Fa ta_func
146 from the task structure is called with the value of the field
147 .Fa ta_context
148 as its first argument
149 and the value of
150 .Fa ta_pending
151 as its second argument.
152 .Pp
153 The
154 .Fn taskqueue_drain
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 .
159 .Pp
160 The
161 .Fn taskqueue_block
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
165 calling
166 .Fn taskqueue_unblock .
167 .Pp
168 The
169 .Fn taskqueue_start_threads
170 function is used to create and start
171 .Fa count
172 dedicated threads for the taskqueue specified by
173 .Fa tqp .
174 These threads will be created with the priority specified by
175 .Fa pri
176 and the name given by
177 .Fa fmt
178 with _N appended to it, where N is the number of the thread.
179 The taskqueue specified by
180 .Fa tqp
181 must be created previously by calling
182 .Fn taskqueue_create
183 with the argument
184 .Fa enqueue
185 set to
186 .Fa taskqueue_thread_enqueue .
187 .Pp
188 A convenience macro,
189 .Fn TASK_INIT
190 is provided to initialise a
191 .Vt task
192 structure.
193 The values of
194 .Fa priority ,
195 .Fa func ,
196 and
197 .Fa context
198 are simply copied into the task structure fields and the
199 .Fa ta_pending
200 field is cleared.
201 .Pp
202 Two macros,
203 .Fn TASKQUEUE_DECLARE
204 and
205 .Fn TASKQUEUE_DEFINE
206 are used to declare a reference to a global queue,
207 and to define the implementation of the queue.
208 The
209 .Fn TASKQUEUE_DEFINE
210 macro arranges to call
211 .Fn taskqueue_create
212 with the values of its
213 .Fa name ,
214 .Fa enqueue
215 and
216 .Fa context
217 arguments during system initialisation.
218 After calling
219 .Fn taskqueue_create ,
220 the
221 .Fa 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 system provides two global taskqueues,
227 .Va taskqueue_swi ,
228 .Va taskqueue_swi_mp ,
229 which are run via a software interrupt mechanism.
230 To use these queues, call
231 .Fn taskqueue_enqueue
232 with the value of the global variable
233 .Va taskqueue_swi or
234 .Va taskqueue_swi_mp .
235 .Pp
236 While
237 .Va taskqueue_swi
238 acquires the mplock for its tasks,
239 .Va taskqueue_swi_mp
240 is intended for mpsafe tasks and no mplock will be acquired for them.
241 These queues can be used,
242 for instance, for implementing interrupt handlers which must perform a
243 significant amount of processing in the handler.
244 The hardware interrupt handler would perform minimal processing of the
245 interrupt and then enqueue a task to finish the work.
246 This reduces to a minimum
247 the amount of time spent with interrupts disabled.
248 .\".Sh SEE ALSO
249 .\".Xr ithread 9 ,
250 .\".Xr kthread 9 ,
251 .\".Xr swi 9
252 .Sh HISTORY
253 This interface first appeared in
254 .Fx 5.0 .
255 There is a similar facility called tqueue in the Linux kernel.
256 .Sh AUTHORS
257 This manual page was written by
258 .An Doug Rabson .