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