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 12, 2000 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)(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 int ta_pending; /* count times queued */ 51 int ta_priority; /* priority of task in queue */ 52 task_fn ta_func; /* task handler */ 53 void *ta_context; /* argument for handler */ 54}; 55 56.Ed 57.Ft struct taskqueue * 58.Fn taskqueue_create "const char *name" "int mflags" "taskqueue_enqueue_fn enqueue" "void *context" 59.Ft void 60.Fn taskqueue_free "struct taskqueue *queue" 61.Ft struct taskqueue * 62.Fn taskqueue_find "const char *name" 63.Ft int 64.Fn taskqueue_enqueue "struct taskqueue *queue" "struct task *task" 65.Ft int 66.Fn taskqueue_enqueue_fast "struct taskqueue *queue" "struct task *task" 67.Ft void 68.Fn taskqueue_run "struct taskqueue *queue" 69.Fn TASK_INIT "struct task *task" "int priority" "task_fn_t *func" "void *context" 70.Fn TASKQUEUE_DECLARE "name" 71.Fn TASKQUEUE_DEFINE "name" "taskqueue_enqueue_fn enqueue" "void *context" "init" 72.Sh DESCRIPTION 73These functions provide a simple interface for asynchronous execution 74of code. 75.Pp 76The function 77.Fn taskqueue_create 78is used to create new queues. 79The arguments to 80.Fn taskqueue_create 81include a name which should be unique, 82a set of 83.Xr malloc 9 84flags which specify whether the call to 85.Fn malloc 86is allowed to sleep 87and a function which is called from 88.Fn taskqueue_enqueue 89when a task is added to the queue 90.\" XXX The rest of the sentence gets lots in relation to the first part. 91to allow the queue to arrange to be run later 92(for instance by scheduling a software interrupt or waking a kernel 93thread). 94.Pp 95The function 96.Fn taskqueue_free 97should be used to remove the queue from the global list of queues 98and free the memory used by the queue. 99Any tasks which are on the queue will be executed at this time. 100.Pp 101The system maintains a list of all queues which can be searched using 102.Fn taskqueue_find . 103The first queue whose name matches is returned, otherwise 104.Dv NULL . 105.Pp 106To add a task to the list of tasks queued on a taskqueue, call 107.Fn taskqueue_enqueue 108with pointers to the queue and task. 109If the task's 110.Va ta_pending 111field is non-zero, 112then it is simply incremented to reflect the number of times the task 113was enqueued. 114Otherwise, 115the task is added to the list before the first task which has a lower 116.Va ta_priority 117value or at the end of the list if no tasks have a lower priority. 118Enqueueing a task does not perform any memory allocation which makes 119it suitable for calling from an interrupt handler. 120This function will return 121.Er EPIPE 122if the queue is being freed. 123.Pp 124The function 125.Fn taskqueue_enqueue_fast 126should be used in place of 127.Fn taskqueue_enqueue 128when the enqueuing must happen from a fast interrupt handler. 129This method uses spin locks to avoid the possibility of sleeping in the fast 130interrupt context. 131.Pp 132To execute all the tasks on a queue, 133call 134.Fn taskqueue_run . 135When a task is executed, 136first it is removed from the queue, 137the value of 138.Va ta_pending 139is recorded and then the field is zeroed. 140The function 141.Va ta_func 142from the task structure is called with the value of the field 143.Va ta_context 144as its first argument 145and the value of 146.Va ta_pending 147as its second argument. 148.Pp 149A convenience macro, 150.Fn TASK_INIT "task" "priority" "func" "context" 151is provided to initialise a 152.Va task 153structure. 154The values of 155.Va priority , 156.Va func , 157and 158.Va context 159are simply copied into the task structure fields and the 160.Va ta_pending 161field is cleared. 162.Pp 163Two macros 164.Fn TASKQUEUE_DECLARE "name" 165and 166.Fn TASKQUEUE_DEFINE "name" "enqueue" "context" "init" 167are used to declare a reference to a global queue 168and to define the implementation of the queue. 169The 170.Fn TASKQUEUE_DEFINE 171macro arranges to call 172.Fn taskqueue_create 173with the values of its 174.Va name , 175.Va enqueue 176and 177.Va context 178arguments during system initialisation. 179After calling 180.Fn taskqueue_create , 181the 182.Va init 183argument to the macro is executed as a C statement, 184allowing any further initialisation to be performed 185(such as registering an interrupt handler etc.) 186.Pp 187The system provides three global taskqueues, 188.Va taskqueue_swi , 189.Va taskqueue_swi_giant , 190and 191.Va taskqueue_thread . 192The swi taskqueues are run via a software interrupt mechanism. 193The taskqueue_swi queue runs without the protection of the Giant kernel lock, 194and the taskqueue_swi_giant queue runs with the protection of the Giant 195kernel lock. 196The thread taskqueue runs in a kernel thread context, and tasks run from 197this thread do not run under the Giant kernel lock. 198If the caller wants to run under Giant, he should explicitly acquire and 199release Giant in his taskqueue handler routine. 200 201To use these queues, 202call 203.Fn taskqueue_enqueue 204with the value of the global taskqueue variable for the queue you wish to 205use ( 206.Va taskqueue_swi , 207.Va taskqueue_swi_giant , 208or 209.Va taskqueue_thread 210). 211.Pp 212The software interrupt queues can be used, 213for instance, for implementing interrupt handlers which must perform a 214significant amount of processing in the handler. 215The hardware interrupt handler would perform minimal processing of the 216interrupt and then enqueue a task to finish the work. 217This reduces to a minimum 218the amount of time spent with interrupts disabled. 219.Pp 220The thread queue can be used, for instance, by interrupt level routines 221that need to call kernel functions that do things that can only be done 222from a thread context. 223(e.g., call malloc with the M_WAITOK flag.) 224.Sh HISTORY 225This interface first appeared in 226.Fx 5.0 . 227There is a similar facility called tqueue in the Linux kernel. 228.Sh AUTHORS 229This man page was written by 230.An Doug Rabson . 231