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