1.\" $OpenBSD: task_add.9,v 1.17 2017/11/13 23:52:49 dlg 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: November 13 2017 $ 18.Dt TASK_ADD 9 19.Os 20.Sh NAME 21.Nm taskq_create , 22.Nm taskq_destroy , 23.Nm taskq_barrier , 24.Nm task_set , 25.Nm task_add , 26.Nm task_del , 27.Nm TASK_INITIALIZER 28.Nd task queues 29.Sh SYNOPSIS 30.In sys/task.h 31.Ft struct taskq * 32.Fo taskq_create 33.Fa "const char *name" 34.Fa "unsigned int nthreads" 35.Fa "int ipl" 36.Fa "unsigned int flags" 37.Fc 38.Ft void 39.Fn taskq_destroy "struct taskq *tq" 40.Ft void 41.Fn taskq_barrier "struct taskq *tq" 42.Ft void 43.Fn task_set "struct task *t" "void (*fn)(void *)" "void *arg" 44.Ft int 45.Fn task_add "struct taskq *tq" "struct task *t" 46.Ft int 47.Fn task_del "struct taskq *tq" "struct task *t" 48.Vt extern struct taskq *const systq; 49.Vt extern struct taskq *const systqmp; 50.Fn TASK_INITIALIZER "void (*fn)(void *)" "void *arg" 51.Sh DESCRIPTION 52The 53taskq 54API provides a mechanism to defer work to a process context. 55.Pp 56.Fn taskq_create 57allocates a taskq and a set of threads to be used to complete work 58that would be inappropriate for the shared system taskq. 59The 60.Fa name 61argument specifies the name of the kernel threads that are created 62to service the work on the taskq. 63.Fa nthreads 64specifies the number of threads that will be created to handle the work. 65.Fa ipl 66specifies the highest interrupt protection level at which 67.Fn task_add 68and 69.Fn task_del 70will be called against the created taskq. 71See 72.Xr spl 9 73for a list of the IPLs. 74The operational characteristics of the taskq 75can be altered by OR'ing the following defines into the 76.Fa flags 77argument: 78.Bl -tag -width xxx -offset indent 79.It Dv TASKQ_MPSAFE 80The threads servicing the taskq will be run without the kernel big lock. 81.It Dv TASKQ_CANTSLEEP 82The tasks run via the taskq cannot sleep. 83.El 84.Pp 85.Fn taskq_destroy 86causes the resources associated with a previously created taskq to be freed. 87It will wait till all the tasks in the work queue are completed before 88returning. 89Calling 90.Fn taskq_destroy 91against the system taskq is an error and will lead to undefined 92behaviour or a system fault. 93.Pp 94.Fn taskq_barrier 95guarantees that any task that was running on the 96.Fa tq 97taskq when the barrier was called has finished by the time the barrier 98returns. 99.Fn taskq_barrier 100is only supported on taskqs serviced by 1 thread, 101and may not be called by a task running in the specified taskq. 102.Pp 103It is the responsibility of the caller to provide the 104.Fn task_set , 105.Fn task_add , 106and 107.Fn task_del 108functions with pre-allocated task structures. 109.Pp 110.Fn task_set 111prepares the task structure 112.Fa t 113to be used in future calls to 114.Fn task_add 115and 116.Fn task_del . 117.Fa t 118will be prepared to call the function 119.Fa fn 120with the argument specified by 121.Fa arg . 122Once initialised, the 123.Fa t 124structure can be used repeatedly in calls to 125.Fn task_add 126and 127.Fn task_del 128and does not need to be reinitialised unless the function called 129and/or its argument must change. 130.Pp 131.Fn task_add 132schedules the execution of the work specified by the 133task structure 134.Fa t 135on the 136.Fa tq 137taskq. 138The task structure must already be initialised by 139.Fn task_set . 140.Pp 141.Fn task_del 142will remove the task structure 143.Fa t 144from the taskq 145.Fa tq . 146If the work was already executed or has not been added to the taskq, 147the call will have no effect. 148Calling 149.Fn task_del 150against a different taskq than the one given in a previous call to 151.Fn task_add 152is an error and will lead to undefined behaviour. 153.Pp 154The kernel provides two system taskqs: 155.Va systq , 156which executes while holding the kernel lock, and 157.Va systqmp , 158which does not hold the kernel lock during execution. 159They can both be used by any subsystem for short lived tasks. 160They are serviced by a single thread and can therefore provide predictable 161ordering of work. 162Work can be scheduled on the system taskqs from callers at or below IPL_HIGH. 163.Pp 164A task declaration can be initialised with the 165.Fn TASK_INITIALIZER 166macro. 167The task will be prepared to call the function specified by the 168.Fa fn 169argument with the 170.Fa void * 171argument given in 172.Fa arg . 173.Sh CONTEXT 174.Fn taskq_create 175and 176.Fn taskq_destroy 177can be called during autoconf, or from process context. 178.Fn taskq_barrier 179can be called from process context. 180.Fn task_set , 181.Fn task_add , 182and 183.Fn task_del 184can be called during autoconf, from process context, or from interrupt context. 185.Sh RETURN VALUES 186.Fn taskq_create 187returns a pointer to a taskq structure on success or 188.Dv NULL 189on failure. 190.Pp 191.Fn task_add 192will return 1 if the task 193.Fa t 194was added to the taskq 195.Fa tq 196or 0 if the task was already queued. 197.Pp 198.Fn task_del 199will return 1 if the task 200.Fa t 201was removed from the taskq 202.Fa tq 203or 0 if the task was not already on the queue. 204.Sh SEE ALSO 205.Xr autoconf 9 , 206.Xr spl 9 207.Sh HISTORY 208The task API was originally written by 209.An David Gwynne Aq Mt dlg@openbsd.org . 210The task API first appeared in 211.Ox 5.5 . 212