1.\" $OpenBSD: task_add.9,v 1.12 2014/06/11 08:47:53 blambert 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 11 2014 $ 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.Fn "taskq_create" "const char *name" "unsigned int nthreads" "int ipl" 32.Ft void 33.Fn "taskq_destroy" "struct taskq *tq" 34.Ft void 35.Fn "task_set" "struct task *t" "void (*fn)(void *, void *)" "void *arg1" "void *arg2" 36.Ft int 37.Fn "task_add" "struct taskq *tq" "struct task *t" 38.Ft int 39.Fn "task_del" "struct taskq *tq" "struct task *t" 40.Vt extern struct taskq *const systq; 41.Vt extern struct taskq *const systqmp; 42.Fn "TASK_INITIALIZER" "void (*fn)(void *, void *)" "void *arg1" "void *arg2" 43.Sh DESCRIPTION 44The 45taskq 46API provides a mechanism to defer work to a process context. 47.Pp 48.Fn taskq_create 49allocates a taskq and a set of threads to be used to complete work 50that would be inappropriate for the shared system taskq. 51The 52.Fa name 53argument specifies the name of the kernel threads that are created 54to service the work on the taskq. 55.Fa nthreads 56specifies the number of threads that will be created to handle the work. 57.Fa ipl 58specifies the highest interrupt protection level at which 59.Fn task_add 60and 61.Fn task_del 62will be called against the created taskq. 63See 64.Xr spl 9 65for a list of the IPLs. 66.Pp 67.Fn taskq_destroy 68causes the resources associated with a previously created taskq to be freed. 69It will wait till all the tasks in the work queue are completed before 70returning. 71Calling 72.Fn taskq_destroy 73against the system taskq is an error and will lead to undefined 74behaviour or a system fault. 75.Pp 76It is the responsibility of the caller to provide the 77.Fn task_set , 78.Fn task_add , 79and 80.Fn task_del 81functions with pre-allocated task structures. 82.Pp 83.Fn task_set 84prepares the task structure 85.Fa t 86to be used in future calls to 87.Fn task_add 88and 89.Fn task_del . 90.Fa t 91will be prepared to call the function 92.Fa fn 93with the arguments specified by 94.Fa arg1 95and 96.Fa arg2 . 97Once initialised, the 98.Fa t 99structure can be used repeatedly in calls to 100.Fn task_add 101and 102.Fn task_del 103and does not need to be reinitialised unless the function called 104and/or its argument must change. 105.Pp 106.Fn task_add 107schedules the execution of the work specified by the 108task structure 109.Fa t 110on the 111.Fa tq 112taskq. 113The task structure must already be initialised by 114.Fn task_set . 115.Pp 116.Fn task_del 117will remove the task structure 118.Fa t 119from the taskq 120.Fa tq . 121If the work was already executed or has not been added to the taskq, 122the call will have no effect. 123Calling 124.Fn task_del 125against a different taskq than the one given in a previous call to 126.Fn task_add 127is an error and will lead to undefined behaviour. 128.Pp 129The kernel provides two system taskqs: 130.Va systq , 131which executes while holding the kernel lock, and 132.Va systqmp , 133which does not hold the kernel lock during execution. 134They can both be used by any subsystem for short lived tasks. 135They are serviced by a single thread and can therefore provide predictable 136ordering of work. 137Work can be scheduled on the system taskqs from callers at or below IPL_HIGH. 138.Pp 139A task declaration can be initialised with the 140.Fn TASK_INITIALIZER 141macro. 142The task will be prepared to call the function specified by the 143.Fa fn 144argument with the 145.Fa void * 146arguments given in 147.Fa arg1 148and 149.Fa arg2 . 150.Sh CONTEXT 151.Fn taskq_create 152and 153.Fn taskq_destroy 154can be called during autoconf, or from process context. 155.Fn task_set , 156.Fn task_add , 157and 158.Fn task_del 159can be called during autoconf, from process context, or from interrupt context. 160.Sh RETURN VALUES 161.Fn taskq_create 162returns a pointer to a taskq structure on success or 163.Dv NULL 164on failure. 165.Pp 166.Fn task_add 167will return 1 if the task 168.Fa t 169was added to the taskq 170.Fa tq 171or 0 if the task was already queued. 172.Pp 173.Fn task_del 174will return 1 if the task 175.Fa t 176was removed from the taskq 177.Fa tq 178or 0 if the task was not already on the queue. 179.Sh SEE ALSO 180.Xr autoconf 9 , 181.Xr spl 9 182.Sh HISTORY 183The task API was originally written by 184.An David Gwynne Aq Mt dlg@openbsd.org . 185The task API first appeared in 186.Ox 5.5 . 187