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 June 13, 2008 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 struct taskqueue * 63.Fn taskqueue_find "const char *name" 64.Ft int 65.Fn taskqueue_enqueue "struct taskqueue *queue" "struct task *task" 66.Ft int 67.Fn taskqueue_enqueue_fast "struct taskqueue *queue" "struct task *task" 68.Ft void 69.Fn taskqueue_run "struct taskqueue *queue" 70.Ft void 71.Fn taskqueue_run_fast "struct taskqueue *queue" 72.Ft void 73.Fn taskqueue_drain "struct taskqueue *queue" "struct task *task" 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 remove the queue from the global list of queues 117and free the memory used by the queue. 118Any tasks that are on the queue will be executed at this time after 119which the thread servicing the queue will be signaled that it should exit. 120.Pp 121The system maintains a list of all queues which can be searched using 122.Fn taskqueue_find . 123The first queue whose name matches is returned, otherwise 124.Dv NULL . 125.Pp 126To add a task to the list of tasks queued on a taskqueue, call 127.Fn taskqueue_enqueue 128with pointers to the queue and task. 129If the task's 130.Va ta_pending 131field is non-zero, 132then it is simply incremented to reflect the number of times the task 133was enqueued. 134Otherwise, 135the task is added to the list before the first task which has a lower 136.Va ta_priority 137value or at the end of the list if no tasks have a lower priority. 138Enqueueing a task does not perform any memory allocation which makes 139it suitable for calling from an interrupt handler. 140This function will return 141.Er EPIPE 142if the queue is being freed. 143.Pp 144The function 145.Fn taskqueue_enqueue_fast 146should be used in place of 147.Fn taskqueue_enqueue 148when the enqueuing must happen from a fast interrupt handler. 149This method uses spin locks to avoid the possibility of sleeping in the fast 150interrupt context. 151.Pp 152To execute all the tasks on a queue, 153call 154.Fn taskqueue_run 155or 156.Fn taskqueue_run_fast 157depending on the flavour of the queue. 158When a task is executed, 159first it is removed from the queue, 160the value of 161.Va ta_pending 162is recorded and then the field is zeroed. 163The function 164.Va ta_func 165from the task structure is called with the value of the field 166.Va ta_context 167as its first argument 168and the value of 169.Va ta_pending 170as its second argument. 171After the function 172.Va ta_func 173returns, 174.Xr wakeup 9 175is called on the task pointer passed to 176.Fn taskqueue_enqueue . 177.Pp 178The 179.Fn taskqueue_drain 180function is used to wait for the task to finish. 181There is no guarantee that the task will not be 182enqueued after call to 183.Fn taskqueue_drain . 184.Pp 185A convenience macro, 186.Fn TASK_INIT "task" "priority" "func" "context" 187is provided to initialise a 188.Va task 189structure. 190The values of 191.Va priority , 192.Va func , 193and 194.Va context 195are simply copied into the task structure fields and the 196.Va ta_pending 197field is cleared. 198.Pp 199Five macros 200.Fn TASKQUEUE_DECLARE "name" , 201.Fn TASKQUEUE_DEFINE "name" "enqueue" "context" "init" , 202.Fn TASKQUEUE_FAST_DEFINE "name" "enqueue" "context" "init" , 203and 204.Fn TASKQUEUE_DEFINE_THREAD "name" 205.Fn TASKQUEUE_FAST_DEFINE_THREAD "name" 206are used to declare a reference to a global queue, to define the 207implementation of the queue, and declare a queue that uses its own thread. 208The 209.Fn TASKQUEUE_DEFINE 210macro arranges to call 211.Fn taskqueue_create 212with the values of its 213.Va name , 214.Va enqueue 215and 216.Va context 217arguments during system initialisation. 218After calling 219.Fn taskqueue_create , 220the 221.Va init 222argument to the macro is executed as a C statement, 223allowing any further initialisation to be performed 224(such as registering an interrupt handler etc.) 225.Pp 226The 227.Fn TASKQUEUE_DEFINE_THREAD 228macro defines a new taskqueue with its own kernel thread to serve tasks. 229The variable 230.Vt struct taskqueue *taskqueue_name 231is used to enqueue tasks onto the queue. 232.Pp 233.Fn TASKQUEUE_FAST_DEFINE 234and 235.Fn TASKQUEUE_FAST_DEFINE_THREAD 236act just like 237.Fn TASKQUEUE_DEFINE 238and 239.Fn TASKQUEUE_DEFINE_THREAD 240respectively but taskqueue is created with 241.Fn taskqueue_create_fast . 242.Ss Predefined Task Queues 243The system provides four global taskqueues, 244.Va taskqueue_fast , 245.Va taskqueue_swi , 246.Va taskqueue_swi_giant , 247and 248.Va taskqueue_thread . 249The 250.Va taskqueue_fast 251queue is for swi handlers dispatched from fast interrupt handlers, 252where sleep mutexes cannot be used. 253The swi taskqueues are run via a software interrupt mechanism. 254The 255.Va taskqueue_swi 256queue runs without the protection of the 257.Va Giant 258kernel lock, and the 259.Va taskqueue_swi_giant 260queue runs with the protection of the 261.Va Giant 262kernel lock. 263The thread taskqueue 264.Va taskqueue_thread 265runs in a kernel thread context, and tasks run from this thread do 266not run under the 267.Va Giant 268kernel lock. 269If the caller wants to run under 270.Va Giant , 271he should explicitly acquire and release 272.Va Giant 273in his taskqueue handler routine. 274.Pp 275To use these queues, 276call 277.Fn taskqueue_enqueue 278with the value of the global taskqueue variable for the queue you wish to 279use 280.Va ( taskqueue_swi , 281.Va taskqueue_swi_giant , 282or 283.Va taskqueue_thread ) . 284Use 285.Fn taskqueue_enqueue_fast 286for the global taskqueue variable 287.Va taskqueue_fast . 288.Pp 289The software interrupt queues can be used, 290for instance, for implementing interrupt handlers which must perform a 291significant amount of processing in the handler. 292The hardware interrupt handler would perform minimal processing of the 293interrupt and then enqueue a task to finish the work. 294This reduces to a minimum 295the amount of time spent with interrupts disabled. 296.Pp 297The thread queue can be used, for instance, by interrupt level routines 298that need to call kernel functions that do things that can only be done 299from a thread context. 300(e.g., call malloc with the M_WAITOK flag.) 301.Pp 302Note that tasks queued on shared taskqueues such as 303.Va taskqueue_swi 304may be delayed an indeterminate amount of time before execution. 305If queueing delays cannot be tolerated then a private taskqueue should 306be created with a dedicated processing thread. 307.Sh SEE ALSO 308.Xr ithread 9 , 309.Xr kthread 9 , 310.Xr swi 9 311.Sh HISTORY 312This interface first appeared in 313.Fx 5.0 . 314There is a similar facility called tqueue in the Linux kernel. 315.Sh AUTHORS 316This manual page was written by 317.An Doug Rabson . 318