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