PageRenderTime 21ms CodeModel.GetById 15ms app.highlight 2ms RepoModel.GetById 2ms app.codeStats 0ms

/share/man/man9/taskqueue.9

https://bitbucket.org/freebsd/freebsd-head/
Unknown | 382 lines | 379 code | 3 blank | 0 comment | 0 complexity | 45ac376fa7c09c41978bee07a78187da MD5 | raw file
  1.\" -*- nroff -*-
  2.\"
  3.\" Copyright (c) 2000 Doug Rabson
  4.\"
  5.\" All rights reserved.
  6.\"
  7.\" This program is free software.
  8.\"
  9.\" Redistribution and use in source and binary forms, with or without
 10.\" modification, are permitted provided that the following conditions
 11.\" are met:
 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.
 17.\"
 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.
 28.\"
 29.\" $FreeBSD$
 30.\"
 31.Dd April 26, 2011
 32.Dt TASKQUEUE 9
 33.Os
 34.Sh NAME
 35.Nm taskqueue
 36.Nd asynchronous task execution
 37.Sh SYNOPSIS
 38.In sys/param.h
 39.In sys/kernel.h
 40.In sys/malloc.h
 41.In sys/queue.h
 42.In sys/taskqueue.h
 43.Bd -literal
 44typedef void (*task_fn_t)(void *context, int pending);
 45
 46typedef void (*taskqueue_enqueue_fn)(void *context);
 47
 48struct task {
 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 */
 54};
 55
 56struct timeout_task;
 57.Ed
 58.Ft struct taskqueue *
 59.Fn taskqueue_create "const char *name" "int mflags" "taskqueue_enqueue_fn enqueue" "void *context"
 60.Ft struct taskqueue *
 61.Fn taskqueue_create_fast "const char *name" "int mflags" "taskqueue_enqueue_fn enqueue" "void *context"
 62.Ft void
 63.Fn taskqueue_free "struct taskqueue *queue"
 64.Ft int
 65.Fn taskqueue_enqueue "struct taskqueue *queue" "struct task *task"
 66.Ft int
 67.Fn taskqueue_enqueue_fast "struct taskqueue *queue" "struct task *task"
 68.Ft int
 69.Fn taskqueue_enqueue_timeout "struct taskqueue *queue" "struct timeout_task *timeout_task" "int ticks"
 70.Ft int
 71.Fn taskqueue_cancel "struct taskqueue *queue" "struct task *task" "u_int *pendp"
 72.Ft int
 73.Fn taskqueue_cancel_timeout "struct taskqueue *queue" "struct timeout_task *timeout_task" "u_int *pendp"
 74.Ft void
 75.Fn taskqueue_drain "struct taskqueue *queue" "struct task *task"
 76.Ft void
 77.Fn taskqueue_drain_timeout "struct taskqueue *queue" "struct timeout_task *timeout_task"
 78.Ft int
 79.Fn taskqueue_member "struct taskqueue *queue" "struct thread *td"
 80.Ft void
 81.Fn taskqueue_run "struct taskqueue *queue"
 82.Fn TASK_INIT "struct task *task" "int priority" "task_fn_t func" "void *context"
 83.Fn TASK_INITIALIZER "int priority" "task_fn_t func" "void *context"
 84.Fn TASKQUEUE_DECLARE "name"
 85.Fn TASKQUEUE_DEFINE "name" "taskqueue_enqueue_fn enqueue" "void *context" "init"
 86.Fn TASKQUEUE_FAST_DEFINE "name" "taskqueue_enqueue_fn enqueue" "void *context" "init"
 87.Fn TASKQUEUE_DEFINE_THREAD "name"
 88.Fn TASKQUEUE_FAST_DEFINE_THREAD "name"
 89.Fn TIMEOUT_TASK_INIT "struct taskqueue *queue" "struct timeout_task *timeout_task" "int priority" "task_fn_t func" "void *context"
 90.Sh DESCRIPTION
 91These functions provide a simple interface for asynchronous execution
 92of code.
 93.Pp
 94The function
 95.Fn taskqueue_create
 96is used to create new queues.
 97The arguments to
 98.Fn taskqueue_create
 99include a name that should be unique,
100a set of
101.Xr malloc 9
102flags that specify whether the call to
103.Fn malloc
104is allowed to sleep,
105a function that is called from
106.Fn taskqueue_enqueue
107when a task is added to the queue,
108and a pointer to the memory location where the identity of the
109thread that services the queue is recorded.
110.\" XXX	The rest of the sentence gets lots in relation to the first part.
111The function called from
112.Fn taskqueue_enqueue
113must arrange for the queue to be processed
114(for instance by scheduling a software interrupt or waking a kernel
115thread).
116The memory location where the thread identity is recorded is used
117to signal the service thread(s) to terminate--when this value is set to
118zero and the thread is signaled it will terminate.
119If the queue is intended for use in fast interrupt handlers
120.Fn taskqueue_create_fast
121should be used in place of
122.Fn taskqueue_create .
123.Pp
124The function
125.Fn taskqueue_free
126should be used to free the memory used by the queue.
127Any tasks that are on the queue will be executed at this time after
128which the thread servicing the queue will be signaled that it should exit.
129.Pp
130To add a task to the list of tasks queued on a taskqueue, call
131.Fn taskqueue_enqueue
132with pointers to the queue and task.
133If the task's
134.Va ta_pending
135field is non-zero,
136then it is simply incremented to reflect the number of times the task
137was enqueued, up to a cap of USHRT_MAX.
138Otherwise,
139the task is added to the list before the first task which has a lower
140.Va ta_priority
141value or at the end of the list if no tasks have a lower priority.
142Enqueueing a task does not perform any memory allocation which makes
143it suitable for calling from an interrupt handler.
144This function will return
145.Er EPIPE
146if the queue is being freed.
147.Pp
148The function
149.Fn taskqueue_enqueue_fast
150should be used in place of
151.Fn taskqueue_enqueue
152when the enqueuing must happen from a fast interrupt handler.
153This method uses spin locks to avoid the possibility of sleeping in the fast
154interrupt context.
155.Pp
156When a task is executed,
157first it is removed from the queue,
158the value of
159.Va ta_pending
160is recorded and then the field is zeroed.
161The function
162.Va ta_func
163from the task structure is called with the value of the field
164.Va ta_context
165as its first argument
166and the value of
167.Va ta_pending
168as its second argument.
169After the function
170.Va ta_func
171returns,
172.Xr wakeup 9
173is called on the task pointer passed to
174.Fn taskqueue_enqueue .
175.Pp
176The
177.Fn taskqueue_enqueue_timeout
178is used to schedule the enqueue after the specified amount of
179.Va ticks .
180Only non-fast task queues can be used for
181.Va timeout_task
182scheduling.
183.Pp
184The
185.Fn taskqueue_cancel
186function is used to cancel a task.
187The
188.Va ta_pending
189count is cleared, and the old value returned in the reference
190parameter
191.Fa pendp ,
192if it is
193.Pf non- Dv NULL .
194If the task is currently running,
195.Dv EBUSY
196is returned, otherwise 0.
197To implement a blocking
198.Fn taskqueue_cancel
199that waits for a running task to finish, it could look like:
200.Bd -literal -offset indent
201while (taskqueue_cancel(tq, task, NULL) != 0)
202	taskqueue_drain(tq, task);
203.Ed
204.Pp
205Note that, as with
206.Fn taskqueue_drain ,
207the caller is responsible for ensuring that the task is not re-enqueued
208after being canceled.
209.Pp
210Similarly, the
211.Fn taskqueue_cancel_timeout
212function is used to cancel the scheduled task execution.
213.Pp
214The
215.Fn taskqueue_drain
216function is used to wait for the task to finish, and
217the
218.Fn taskqueue_drain_timeout
219function is used to wait for the scheduled task to finish.
220There is no guarantee that the task will not be
221enqueued after call to
222.Fn taskqueue_drain .
223.Pp
224The
225.Fn taskqueue_member
226function returns
227.No 1
228if the given thread
229.Fa td
230is part of the given taskqueue
231.Fa queue
232and
233.No 0
234otherwise.
235.Pp
236The
237.Fn taskqueue_run
238function will run all pending tasks in the specified
239.Fa queue .
240Normally this function is only used internally.
241.Pp
242A convenience macro,
243.Fn TASK_INIT "task" "priority" "func" "context"
244is provided to initialise a
245.Va task
246structure.
247The
248.Fn TASK_INITIALIZER
249macro generates an initializer for a task structure.
250A macro
251.Fn TIMEOUT_TASK_INIT "queue" "timeout_task" "priority" "func" "context"
252initializes the
253.Va timeout_task
254structure.
255The values of
256.Va priority ,
257.Va func ,
258and
259.Va context
260are simply copied into the task structure fields and the
261.Va ta_pending
262field is cleared.
263.Pp
264Five macros
265.Fn TASKQUEUE_DECLARE "name" ,
266.Fn TASKQUEUE_DEFINE "name" "enqueue" "context" "init" ,
267.Fn TASKQUEUE_FAST_DEFINE "name" "enqueue" "context" "init" ,
268and
269.Fn TASKQUEUE_DEFINE_THREAD "name"
270.Fn TASKQUEUE_FAST_DEFINE_THREAD "name"
271are used to declare a reference to a global queue, to define the
272implementation of the queue, and declare a queue that uses its own thread.
273The
274.Fn TASKQUEUE_DEFINE
275macro arranges to call
276.Fn taskqueue_create
277with the values of its
278.Va name ,
279.Va enqueue
280and
281.Va context
282arguments during system initialisation.
283After calling
284.Fn taskqueue_create ,
285the
286.Va init
287argument to the macro is executed as a C statement,
288allowing any further initialisation to be performed
289(such as registering an interrupt handler etc.)
290.Pp
291The
292.Fn TASKQUEUE_DEFINE_THREAD
293macro defines a new taskqueue with its own kernel thread to serve tasks.
294The variable
295.Vt struct taskqueue *taskqueue_name
296is used to enqueue tasks onto the queue.
297.Pp
298.Fn TASKQUEUE_FAST_DEFINE
299and
300.Fn TASKQUEUE_FAST_DEFINE_THREAD
301act just like
302.Fn TASKQUEUE_DEFINE
303and
304.Fn TASKQUEUE_DEFINE_THREAD
305respectively but taskqueue is created with
306.Fn taskqueue_create_fast .
307.Ss Predefined Task Queues
308The system provides four global taskqueues,
309.Va taskqueue_fast ,
310.Va taskqueue_swi ,
311.Va taskqueue_swi_giant ,
312and
313.Va taskqueue_thread .
314The
315.Va taskqueue_fast
316queue is for swi handlers dispatched from fast interrupt handlers,
317where sleep mutexes cannot be used.
318The swi taskqueues are run via a software interrupt mechanism.
319The
320.Va taskqueue_swi
321queue runs without the protection of the
322.Va Giant
323kernel lock, and the
324.Va taskqueue_swi_giant
325queue runs with the protection of the
326.Va Giant
327kernel lock.
328The thread taskqueue
329.Va taskqueue_thread
330runs in a kernel thread context, and tasks run from this thread do
331not run under the
332.Va Giant
333kernel lock.
334If the caller wants to run under
335.Va Giant ,
336he should explicitly acquire and release
337.Va Giant
338in his taskqueue handler routine.
339.Pp
340To use these queues,
341call
342.Fn taskqueue_enqueue
343with the value of the global taskqueue variable for the queue you wish to
344use
345.Va ( taskqueue_swi ,
346.Va taskqueue_swi_giant ,
347or
348.Va taskqueue_thread ) .
349Use
350.Fn taskqueue_enqueue_fast
351for the global taskqueue variable
352.Va taskqueue_fast .
353.Pp
354The software interrupt queues can be used,
355for instance, for implementing interrupt handlers which must perform a
356significant amount of processing in the handler.
357The hardware interrupt handler would perform minimal processing of the
358interrupt and then enqueue a task to finish the work.
359This reduces to a minimum
360the amount of time spent with interrupts disabled.
361.Pp
362The thread queue can be used, for instance, by interrupt level routines
363that need to call kernel functions that do things that can only be done
364from a thread context.
365(e.g., call malloc with the M_WAITOK flag.)
366.Pp
367Note that tasks queued on shared taskqueues such as
368.Va taskqueue_swi
369may be delayed an indeterminate amount of time before execution.
370If queueing delays cannot be tolerated then a private taskqueue should
371be created with a dedicated processing thread.
372.Sh SEE ALSO
373.Xr ithread 9 ,
374.Xr kthread 9 ,
375.Xr swi 9
376.Sh HISTORY
377This interface first appeared in
378.Fx 5.0 .
379There is a similar facility called work_queue in the Linux kernel.
380.Sh AUTHORS
381This manual page was written by
382.An Doug Rabson .