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