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