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"
73 .Fn TASK_INIT "struct task *task" "int priority" "task_fn_t *func" "void *context"
74 .Fn TASKQUEUE_DECLARE "name"
75 .Fn TASKQUEUE_DEFINE "name" "taskqueue_enqueue_fn enqueue" "void *context" "init"
77 These functions provide a simple interface for asynchronous execution
82 is used to create new queues.
85 include a name that should be unique,
88 flags that specify whether the call to
91 and a function which is called from
93 when a task is added to the queue
94 .\" XXX The rest of the sentence gets lots in relation to the first part.
95 to allow the queue to arrange to be run later
96 (for instance by scheduling a software interrupt or waking a kernel
101 should be used to remove the queue from the global list of queues
102 and free the memory used by the queue.
103 Any tasks that are on the queue will be executed at this time.
105 The system maintains a list of all queues which can be searched using
107 The first queue whose name matches is returned, otherwise
110 To add a task to the list of tasks queued on a taskqueue, call
111 .Fn taskqueue_enqueue
112 with pointers to the queue and task.
116 then it is simply incremented to reflect the number of times the task
119 the task is added to the list before the first task which has a lower
121 value or at the end of the list if no tasks have a lower priority.
122 Enqueueing a task does not perform any memory allocation which makes
123 it suitable for calling from an interrupt handler.
124 This function will return
126 if the queue is being freed.
128 To execute all the tasks on a queue,
131 When a task is executed,
132 first it is removed from the queue,
135 is recorded and then the field is zeroed.
138 from the task structure is called with the value of the field
140 as its first argument
143 as its second argument.
147 is provided to initialise a
155 are simply copied into the task structure fields and the
160 .Fn TASKQUEUE_DECLARE
163 are used to declare a reference to a global queue,
164 and to define the implementation of the queue.
167 macro arranges to call
169 with the values of its
174 arguments during system initialisation.
176 .Fn taskqueue_create ,
179 argument to the macro is executed as a C statement,
180 allowing any further initialisation to be performed
181 (such as registering an interrupt handler etc.)
183 The system provides a global taskqueue,
185 which is run via a software interrupt mechanism.
186 To use this queue, call
187 .Fn taskqueue_enqueue
188 with the value of the global variable
191 This queue can be used,
192 for instance, for implementing interrupt handlers which must perform a
193 significant amount of processing in the handler.
194 The hardware interrupt handler would perform minimal processing of the
195 interrupt and then enqueue a task to finish the work.
196 This reduces to a minimum
197 the amount of time spent with interrupts disabled.
203 This interface first appeared in
205 There is a similar facility called tqueue in the Linux kernel.
207 This manual page was written by