1.\" $OpenBSD: task_add.9,v 1.16 2015/09/14 15:14:55 schwarze Exp $ 2.\" 3.\" Copyright (c) 2013 David Gwynne <dlg@openbsd.org> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: September 14 2015 $ 18.Dt TASK_ADD 9 19.Os 20.Sh NAME 21.Nm taskq_create , 22.Nm taskq_destroy , 23.Nm task_set , 24.Nm task_add , 25.Nm task_del , 26.Nm TASK_INITIALIZER 27.Nd task queues 28.Sh SYNOPSIS 29.In sys/task.h 30.Ft struct taskq * 31.Fo taskq_create 32.Fa "const char *name" 33.Fa "unsigned int nthreads" 34.Fa "int ipl" 35.Fa "unsigned int flags" 36.Fc 37.Ft void 38.Fn taskq_destroy "struct taskq *tq" 39.Ft void 40.Fn task_set "struct task *t" "void (*fn)(void *)" "void *arg" 41.Ft int 42.Fn task_add "struct taskq *tq" "struct task *t" 43.Ft int 44.Fn task_del "struct taskq *tq" "struct task *t" 45.Vt extern struct taskq *const systq; 46.Vt extern struct taskq *const systqmp; 47.Fn TASK_INITIALIZER "void (*fn)(void *)" "void *arg" 48.Sh DESCRIPTION 49The 50taskq 51API provides a mechanism to defer work to a process context. 52.Pp 53.Fn taskq_create 54allocates a taskq and a set of threads to be used to complete work 55that would be inappropriate for the shared system taskq. 56The 57.Fa name 58argument specifies the name of the kernel threads that are created 59to service the work on the taskq. 60.Fa nthreads 61specifies the number of threads that will be created to handle the work. 62.Fa ipl 63specifies the highest interrupt protection level at which 64.Fn task_add 65and 66.Fn task_del 67will be called against the created taskq. 68See 69.Xr spl 9 70for a list of the IPLs. 71The operational characteristics of the taskq 72can be altered by OR'ing the following defines into the 73.Fa flags 74argument: 75.Bl -tag -width xxx -offset indent 76.It Dv TASKQ_MPSAFE 77The threads servicing the taskq will be run without the kernel big lock. 78.It Dv TASKQ_CANTSLEEP 79The tasks run via the taskq cannot sleep. 80.El 81.Pp 82.Fn taskq_destroy 83causes the resources associated with a previously created taskq to be freed. 84It will wait till all the tasks in the work queue are completed before 85returning. 86Calling 87.Fn taskq_destroy 88against the system taskq is an error and will lead to undefined 89behaviour or a system fault. 90.Pp 91It is the responsibility of the caller to provide the 92.Fn task_set , 93.Fn task_add , 94and 95.Fn task_del 96functions with pre-allocated task structures. 97.Pp 98.Fn task_set 99prepares the task structure 100.Fa t 101to be used in future calls to 102.Fn task_add 103and 104.Fn task_del . 105.Fa t 106will be prepared to call the function 107.Fa fn 108with the argument specified by 109.Fa arg . 110Once initialised, the 111.Fa t 112structure can be used repeatedly in calls to 113.Fn task_add 114and 115.Fn task_del 116and does not need to be reinitialised unless the function called 117and/or its argument must change. 118.Pp 119.Fn task_add 120schedules the execution of the work specified by the 121task structure 122.Fa t 123on the 124.Fa tq 125taskq. 126The task structure must already be initialised by 127.Fn task_set . 128.Pp 129.Fn task_del 130will remove the task structure 131.Fa t 132from the taskq 133.Fa tq . 134If the work was already executed or has not been added to the taskq, 135the call will have no effect. 136Calling 137.Fn task_del 138against a different taskq than the one given in a previous call to 139.Fn task_add 140is an error and will lead to undefined behaviour. 141.Pp 142The kernel provides two system taskqs: 143.Va systq , 144which executes while holding the kernel lock, and 145.Va systqmp , 146which does not hold the kernel lock during execution. 147They can both be used by any subsystem for short lived tasks. 148They are serviced by a single thread and can therefore provide predictable 149ordering of work. 150Work can be scheduled on the system taskqs from callers at or below IPL_HIGH. 151.Pp 152A task declaration can be initialised with the 153.Fn TASK_INITIALIZER 154macro. 155The task will be prepared to call the function specified by the 156.Fa fn 157argument with the 158.Fa void * 159argument given in 160.Fa arg . 161.Sh CONTEXT 162.Fn taskq_create 163and 164.Fn taskq_destroy 165can be called during autoconf, or from process context. 166.Fn task_set , 167.Fn task_add , 168and 169.Fn task_del 170can be called during autoconf, from process context, or from interrupt context. 171.Sh RETURN VALUES 172.Fn taskq_create 173returns a pointer to a taskq structure on success or 174.Dv NULL 175on failure. 176.Pp 177.Fn task_add 178will return 1 if the task 179.Fa t 180was added to the taskq 181.Fa tq 182or 0 if the task was already queued. 183.Pp 184.Fn task_del 185will return 1 if the task 186.Fa t 187was removed from the taskq 188.Fa tq 189or 0 if the task was not already on the queue. 190.Sh SEE ALSO 191.Xr autoconf 9 , 192.Xr spl 9 193.Sh HISTORY 194The task API was originally written by 195.An David Gwynne Aq Mt dlg@openbsd.org . 196The task API first appeared in 197.Ox 5.5 . 198