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.\"
| 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: head/share/man/man9/taskqueue.9 146412 2005-05-19 18:31:42Z glebius $
| 29.\" $FreeBSD: head/share/man/man9/taskqueue.9 147398 2005-06-15 13:31:23Z ru $
|
30.\"
31.Dd May 19, 2005
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.Ed
56.Ft struct taskqueue *
57.Fn taskqueue_create "const char *name" "int mflags" "taskqueue_enqueue_fn enqueue" "void *context" "struct proc **"
58.Ft void
59.Fn taskqueue_free "struct taskqueue *queue"
60.Ft struct taskqueue *
61.Fn taskqueue_find "const char *name"
62.Ft int
63.Fn taskqueue_enqueue "struct taskqueue *queue" "struct task *task"
64.Ft int
65.Fn taskqueue_enqueue_fast "struct taskqueue *queue" "struct task *task"
66.Ft void
67.Fn taskqueue_run "struct taskqueue *queue"
68.Ft void
69.Fn taskqueue_run_fast "struct taskqueue *queue"
70.Ft void
71.Fn taskqueue_drain "struct taskqueue *queue" "struct task *task"
72.Fn TASK_INIT "struct task *task" "int priority" "task_fn_t *func" "void *context"
73.Fn TASKQUEUE_DECLARE "name"
74.Fn TASKQUEUE_DEFINE "name" "taskqueue_enqueue_fn enqueue" "void *context" "init"
75.Fn TASKQUEUE_DEFINE_THREAD "name"
76.Sh DESCRIPTION
77These functions provide a simple interface for asynchronous execution
78of code.
79.Pp
80The function
81.Fn taskqueue_create
82is used to create new queues.
83The arguments to
84.Fn taskqueue_create
85include a name that should be unique,
86a set of
87.Xr malloc 9
88flags that specify whether the call to
89.Fn malloc
90is allowed to sleep,
91a function that is called from
92.Fn taskqueue_enqueue
93when a task is added to the queue,
94and a pointer to the memory location where the identity of the
95thread that services the queue is recorded.
96.\" XXX The rest of the sentence gets lots in relation to the first part.
97The function called from
98.Fn taskqueue_enqueue
99must arrange for the queue to be processed
100(for instance by scheduling a software interrupt or waking a kernel
101thread).
102The memory location where the thread identity is recorded is used
103to signal the service thread(s) to terminate--when this value is set to
104zero and the thread is signaled it will terminate.
105.Pp
106The function
107.Fn taskqueue_free
108should be used to remove the queue from the global list of queues
109and free the memory used by the queue.
110Any tasks that are on the queue will be executed at this time after
111which the thread servicing the queue will be signaled that it should exit.
112.Pp
113The system maintains a list of all queues which can be searched using
114.Fn taskqueue_find .
115The first queue whose name matches is returned, otherwise
116.Dv NULL .
117.Pp
118To add a task to the list of tasks queued on a taskqueue, call
119.Fn taskqueue_enqueue
120with pointers to the queue and task.
121If the task's
122.Va ta_pending
123field is non-zero,
124then it is simply incremented to reflect the number of times the task
125was enqueued.
126Otherwise,
127the task is added to the list before the first task which has a lower
128.Va ta_priority
129value or at the end of the list if no tasks have a lower priority.
130Enqueueing a task does not perform any memory allocation which makes
131it suitable for calling from an interrupt handler.
132This function will return
133.Er EPIPE
134if the queue is being freed.
135.Pp
136The function
137.Fn taskqueue_enqueue_fast
138should be used in place of
139.Fn taskqueue_enqueue
140when the enqueuing must happen from a fast interrupt handler.
141This method uses spin locks to avoid the possibility of sleeping in the fast
142interrupt context.
143.Pp
144To execute all the tasks on a queue,
145call
146.Fn taskqueue_run
147or
148.Fn taskqueue_run_fast
149depending on the flavour of the queue.
150When a task is executed,
151first it is removed from the queue,
152the value of
153.Va ta_pending
154is recorded and then the field is zeroed.
155The function
156.Va ta_func
157from the task structure is called with the value of the field
158.Va ta_context
159as its first argument
160and the value of
161.Va ta_pending
162as its second argument.
163.Pp
| 30.\"
31.Dd May 19, 2005
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.Ed
56.Ft struct taskqueue *
57.Fn taskqueue_create "const char *name" "int mflags" "taskqueue_enqueue_fn enqueue" "void *context" "struct proc **"
58.Ft void
59.Fn taskqueue_free "struct taskqueue *queue"
60.Ft struct taskqueue *
61.Fn taskqueue_find "const char *name"
62.Ft int
63.Fn taskqueue_enqueue "struct taskqueue *queue" "struct task *task"
64.Ft int
65.Fn taskqueue_enqueue_fast "struct taskqueue *queue" "struct task *task"
66.Ft void
67.Fn taskqueue_run "struct taskqueue *queue"
68.Ft void
69.Fn taskqueue_run_fast "struct taskqueue *queue"
70.Ft void
71.Fn taskqueue_drain "struct taskqueue *queue" "struct task *task"
72.Fn TASK_INIT "struct task *task" "int priority" "task_fn_t *func" "void *context"
73.Fn TASKQUEUE_DECLARE "name"
74.Fn TASKQUEUE_DEFINE "name" "taskqueue_enqueue_fn enqueue" "void *context" "init"
75.Fn TASKQUEUE_DEFINE_THREAD "name"
76.Sh DESCRIPTION
77These functions provide a simple interface for asynchronous execution
78of code.
79.Pp
80The function
81.Fn taskqueue_create
82is used to create new queues.
83The arguments to
84.Fn taskqueue_create
85include a name that should be unique,
86a set of
87.Xr malloc 9
88flags that specify whether the call to
89.Fn malloc
90is allowed to sleep,
91a function that is called from
92.Fn taskqueue_enqueue
93when a task is added to the queue,
94and a pointer to the memory location where the identity of the
95thread that services the queue is recorded.
96.\" XXX The rest of the sentence gets lots in relation to the first part.
97The function called from
98.Fn taskqueue_enqueue
99must arrange for the queue to be processed
100(for instance by scheduling a software interrupt or waking a kernel
101thread).
102The memory location where the thread identity is recorded is used
103to signal the service thread(s) to terminate--when this value is set to
104zero and the thread is signaled it will terminate.
105.Pp
106The function
107.Fn taskqueue_free
108should be used to remove the queue from the global list of queues
109and free the memory used by the queue.
110Any tasks that are on the queue will be executed at this time after
111which the thread servicing the queue will be signaled that it should exit.
112.Pp
113The system maintains a list of all queues which can be searched using
114.Fn taskqueue_find .
115The first queue whose name matches is returned, otherwise
116.Dv NULL .
117.Pp
118To add a task to the list of tasks queued on a taskqueue, call
119.Fn taskqueue_enqueue
120with pointers to the queue and task.
121If the task's
122.Va ta_pending
123field is non-zero,
124then it is simply incremented to reflect the number of times the task
125was enqueued.
126Otherwise,
127the task is added to the list before the first task which has a lower
128.Va ta_priority
129value or at the end of the list if no tasks have a lower priority.
130Enqueueing a task does not perform any memory allocation which makes
131it suitable for calling from an interrupt handler.
132This function will return
133.Er EPIPE
134if the queue is being freed.
135.Pp
136The function
137.Fn taskqueue_enqueue_fast
138should be used in place of
139.Fn taskqueue_enqueue
140when the enqueuing must happen from a fast interrupt handler.
141This method uses spin locks to avoid the possibility of sleeping in the fast
142interrupt context.
143.Pp
144To execute all the tasks on a queue,
145call
146.Fn taskqueue_run
147or
148.Fn taskqueue_run_fast
149depending on the flavour of the queue.
150When a task is executed,
151first it is removed from the queue,
152the value of
153.Va ta_pending
154is recorded and then the field is zeroed.
155The function
156.Va ta_func
157from the task structure is called with the value of the field
158.Va ta_context
159as its first argument
160and the value of
161.Va ta_pending
162as its second argument.
163.Pp
|
164The
| 164The
|
165.Fn taskqueue_drain
166function is used to wait for the task to finish.
167There is no guarantee that the task will not be
168enqueued after call to
169.Fn taskqueue_drain .
170.Pp
171A convenience macro,
172.Fn TASK_INIT "task" "priority" "func" "context"
173is provided to initialise a
174.Va task
175structure.
176The values of
177.Va priority ,
178.Va func ,
179and
180.Va context
181are simply copied into the task structure fields and the
182.Va ta_pending
183field is cleared.
184.Pp
185Three macros
186.Fn TASKQUEUE_DECLARE "name" ,
187.Fn TASKQUEUE_DEFINE "name" "enqueue" "context" "init" ,
188and
189.Fn TASKQUEUE_DEFINE_THREAD "name"
190are used to declare a reference to a global queue, to define the
191implementation of the queue, and declare a queue that uses its own thread.
192The
193.Fn TASKQUEUE_DEFINE
194macro arranges to call
195.Fn taskqueue_create
196with the values of its
197.Va name ,
198.Va enqueue
199and
200.Va context
201arguments during system initialisation.
202After calling
203.Fn taskqueue_create ,
204the
205.Va init
206argument to the macro is executed as a C statement,
207allowing any further initialisation to be performed
208(such as registering an interrupt handler etc.)
209.Pp
210The
211.Fn TASKQUEUE_DEFINE_THREAD
212macro defines a new taskqueue with its own kernel thread to serve tasks.
213The variable
214.Vt struct proc *taskqueue_name_proc
215is defined which contains the kernel thread serving the tasks.
216The variable
217.Vt struct taskqueue *taskqueue_name
218is used to enqueue tasks onto the queue.
219.Ss Predefined Task Queues
220The system provides four global taskqueues,
221.Va taskqueue_fast ,
222.Va taskqueue_swi ,
223.Va taskqueue_swi_giant ,
224and
225.Va taskqueue_thread .
226The
227.Va taskqueue_fast
228queue is for swi handlers dispatched from fast interrupt handlers,
229where sleep mutexes cannot be used.
230The swi taskqueues are run via a software interrupt mechanism.
231The
232.Va taskqueue_swi
233queue runs without the protection of the
234.Va Giant
235kernel lock, and the
236.Va taskqueue_swi_giant
237queue runs with the protection of the
238.Va Giant
239kernel lock.
240The thread taskqueue
241.Va taskqueue_thread
242runs in a kernel thread context, and tasks run from this thread do
243not run under the
244.Va Giant
245kernel lock.
246If the caller wants to run under
247.Va Giant ,
248he should explicitly acquire and release
249.Va Giant
250in his taskqueue handler routine.
251.Pp
252To use these queues,
253call
254.Fn taskqueue_enqueue
255with the value of the global taskqueue variable for the queue you wish to
256use
257.Va ( taskqueue_swi ,
258.Va taskqueue_swi_giant ,
259or
260.Va taskqueue_thread ) .
261Use
262.Fn taskqueue_enqueue_fast
263for the global taskqueue variable
264.Va taskqueue_fast .
265.Pp
266The software interrupt queues can be used,
267for instance, for implementing interrupt handlers which must perform a
268significant amount of processing in the handler.
269The hardware interrupt handler would perform minimal processing of the
270interrupt and then enqueue a task to finish the work.
271This reduces to a minimum
272the amount of time spent with interrupts disabled.
273.Pp
274The thread queue can be used, for instance, by interrupt level routines
275that need to call kernel functions that do things that can only be done
276from a thread context.
277(e.g., call malloc with the M_WAITOK flag.)
278.Pp
279Note that tasks queued on shared taskqueues such as
280.Va taskqueue_swi
281may be delayed an indeterminate amount of time before execution.
282If queueing delays cannot be tolerated then a private taskqueue should
283be created with a dedicated processing thread.
284.Sh SEE ALSO
285.Xr ithread 9 ,
286.Xr kthread 9 ,
287.Xr swi 9
288.Sh HISTORY
289This interface first appeared in
290.Fx 5.0 .
291There is a similar facility called tqueue in the Linux kernel.
292.Sh AUTHORS
293This man page was written by
294.An Doug Rabson .
295.Sh BUGS
296There is no
297.Fn taskqueue_create_fast .
| 165.Fn taskqueue_drain
166function is used to wait for the task to finish.
167There is no guarantee that the task will not be
168enqueued after call to
169.Fn taskqueue_drain .
170.Pp
171A convenience macro,
172.Fn TASK_INIT "task" "priority" "func" "context"
173is provided to initialise a
174.Va task
175structure.
176The values of
177.Va priority ,
178.Va func ,
179and
180.Va context
181are simply copied into the task structure fields and the
182.Va ta_pending
183field is cleared.
184.Pp
185Three macros
186.Fn TASKQUEUE_DECLARE "name" ,
187.Fn TASKQUEUE_DEFINE "name" "enqueue" "context" "init" ,
188and
189.Fn TASKQUEUE_DEFINE_THREAD "name"
190are used to declare a reference to a global queue, to define the
191implementation of the queue, and declare a queue that uses its own thread.
192The
193.Fn TASKQUEUE_DEFINE
194macro arranges to call
195.Fn taskqueue_create
196with the values of its
197.Va name ,
198.Va enqueue
199and
200.Va context
201arguments during system initialisation.
202After calling
203.Fn taskqueue_create ,
204the
205.Va init
206argument to the macro is executed as a C statement,
207allowing any further initialisation to be performed
208(such as registering an interrupt handler etc.)
209.Pp
210The
211.Fn TASKQUEUE_DEFINE_THREAD
212macro defines a new taskqueue with its own kernel thread to serve tasks.
213The variable
214.Vt struct proc *taskqueue_name_proc
215is defined which contains the kernel thread serving the tasks.
216The variable
217.Vt struct taskqueue *taskqueue_name
218is used to enqueue tasks onto the queue.
219.Ss Predefined Task Queues
220The system provides four global taskqueues,
221.Va taskqueue_fast ,
222.Va taskqueue_swi ,
223.Va taskqueue_swi_giant ,
224and
225.Va taskqueue_thread .
226The
227.Va taskqueue_fast
228queue is for swi handlers dispatched from fast interrupt handlers,
229where sleep mutexes cannot be used.
230The swi taskqueues are run via a software interrupt mechanism.
231The
232.Va taskqueue_swi
233queue runs without the protection of the
234.Va Giant
235kernel lock, and the
236.Va taskqueue_swi_giant
237queue runs with the protection of the
238.Va Giant
239kernel lock.
240The thread taskqueue
241.Va taskqueue_thread
242runs in a kernel thread context, and tasks run from this thread do
243not run under the
244.Va Giant
245kernel lock.
246If the caller wants to run under
247.Va Giant ,
248he should explicitly acquire and release
249.Va Giant
250in his taskqueue handler routine.
251.Pp
252To use these queues,
253call
254.Fn taskqueue_enqueue
255with the value of the global taskqueue variable for the queue you wish to
256use
257.Va ( taskqueue_swi ,
258.Va taskqueue_swi_giant ,
259or
260.Va taskqueue_thread ) .
261Use
262.Fn taskqueue_enqueue_fast
263for the global taskqueue variable
264.Va taskqueue_fast .
265.Pp
266The software interrupt queues can be used,
267for instance, for implementing interrupt handlers which must perform a
268significant amount of processing in the handler.
269The hardware interrupt handler would perform minimal processing of the
270interrupt and then enqueue a task to finish the work.
271This reduces to a minimum
272the amount of time spent with interrupts disabled.
273.Pp
274The thread queue can be used, for instance, by interrupt level routines
275that need to call kernel functions that do things that can only be done
276from a thread context.
277(e.g., call malloc with the M_WAITOK flag.)
278.Pp
279Note that tasks queued on shared taskqueues such as
280.Va taskqueue_swi
281may be delayed an indeterminate amount of time before execution.
282If queueing delays cannot be tolerated then a private taskqueue should
283be created with a dedicated processing thread.
284.Sh SEE ALSO
285.Xr ithread 9 ,
286.Xr kthread 9 ,
287.Xr swi 9
288.Sh HISTORY
289This interface first appeared in
290.Fx 5.0 .
291There is a similar facility called tqueue in the Linux kernel.
292.Sh AUTHORS
293This man page was written by
294.An Doug Rabson .
295.Sh BUGS
296There is no
297.Fn taskqueue_create_fast .
|