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 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. 163After the function 164.Va ta_func 165returns, 166.Xr wakeup 9 167is called on the task pointer passed to 168.Fn taskqueue_enqueue . 169.Pp 170The 171.Fn taskqueue_drain 172function is used to wait for the task to finish. 173There is no guarantee that the task will not be 174enqueued after call to 175.Fn taskqueue_drain . 176.Pp 177A convenience macro, 178.Fn TASK_INIT "task" "priority" "func" "context" 179is provided to initialise a 180.Va task 181structure. 182The values of 183.Va priority , 184.Va func , 185and 186.Va context 187are simply copied into the task structure fields and the 188.Va ta_pending 189field is cleared. 190.Pp 191Three macros 192.Fn TASKQUEUE_DECLARE "name" , 193.Fn TASKQUEUE_DEFINE "name" "enqueue" "context" "init" , 194and 195.Fn TASKQUEUE_DEFINE_THREAD "name" 196are used to declare a reference to a global queue, to define the 197implementation of the queue, and declare a queue that uses its own thread. 198The 199.Fn TASKQUEUE_DEFINE 200macro arranges to call 201.Fn taskqueue_create 202with the values of its 203.Va name , 204.Va enqueue 205and 206.Va context 207arguments during system initialisation. 208After calling 209.Fn taskqueue_create , 210the 211.Va init 212argument to the macro is executed as a C statement, 213allowing any further initialisation to be performed 214(such as registering an interrupt handler etc.) 215.Pp 216The 217.Fn TASKQUEUE_DEFINE_THREAD 218macro defines a new taskqueue with its own kernel thread to serve tasks. 219The variable 220.Vt struct proc *taskqueue_name_proc 221is defined which contains the kernel thread serving the tasks. 222The variable 223.Vt struct taskqueue *taskqueue_name 224is used to enqueue tasks onto the queue. 225.Ss Predefined Task Queues 226The system provides four global taskqueues, 227.Va taskqueue_fast , 228.Va taskqueue_swi , 229.Va taskqueue_swi_giant , 230and 231.Va taskqueue_thread . 232The 233.Va taskqueue_fast 234queue is for swi handlers dispatched from fast interrupt handlers, 235where sleep mutexes cannot be used. 236The swi taskqueues are run via a software interrupt mechanism. 237The 238.Va taskqueue_swi 239queue runs without the protection of the 240.Va Giant 241kernel lock, and the 242.Va taskqueue_swi_giant 243queue runs with the protection of the 244.Va Giant 245kernel lock. 246The thread taskqueue 247.Va taskqueue_thread 248runs in a kernel thread context, and tasks run from this thread do 249not run under the 250.Va Giant 251kernel lock. 252If the caller wants to run under 253.Va Giant , 254he should explicitly acquire and release 255.Va Giant 256in his taskqueue handler routine. 257.Pp 258To use these queues, 259call 260.Fn taskqueue_enqueue 261with the value of the global taskqueue variable for the queue you wish to 262use 263.Va ( taskqueue_swi , 264.Va taskqueue_swi_giant , 265or 266.Va taskqueue_thread ) . 267Use 268.Fn taskqueue_enqueue_fast 269for the global taskqueue variable 270.Va taskqueue_fast . 271.Pp 272The software interrupt queues can be used, 273for instance, for implementing interrupt handlers which must perform a 274significant amount of processing in the handler. 275The hardware interrupt handler would perform minimal processing of the 276interrupt and then enqueue a task to finish the work. 277This reduces to a minimum 278the amount of time spent with interrupts disabled. 279.Pp 280The thread queue can be used, for instance, by interrupt level routines 281that need to call kernel functions that do things that can only be done 282from a thread context. 283(e.g., call malloc with the M_WAITOK flag.) 284.Pp 285Note that tasks queued on shared taskqueues such as 286.Va taskqueue_swi 287may be delayed an indeterminate amount of time before execution. 288If queueing delays cannot be tolerated then a private taskqueue should 289be created with a dedicated processing thread. 290.Sh SEE ALSO 291.Xr ithread 9 , 292.Xr kthread 9 , 293.Xr swi 9 294.Sh HISTORY 295This interface first appeared in 296.Fx 5.0 . 297There is a similar facility called tqueue in the Linux kernel. 298.Sh AUTHORS 299This manual page was written by 300.An Doug Rabson . 301.Sh BUGS 302There is no 303.Fn taskqueue_create_fast . 304