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