share/man/man9/taskqueue.9

   1 .\" -*- nroff -*-
   2 .\"
   3 .\" Copyright (c) 2000 Doug Rabson
   4 .\"
   5 .\" All rights reserved.
   6 .\"
   7 .\" This program is free software.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
  19 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  20 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  21 .\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
  22 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  23 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  24 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  25 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  26 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  27 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  28 .\"
  29 .\" $FreeBSD$
  30 .\"
  31 .Dd May 19, 2005
  32 .Dt TASKQUEUE 9
  33 .Os
  34 .Sh NAME
  35 .Nm taskqueue
  36 .Nd asynchronous task execution
  37 .Sh SYNOPSIS
  38 .In sys/param.h
  39 .In sys/kernel.h
  40 .In sys/malloc.h
  41 .In sys/queue.h
  42 .In sys/taskqueue.h
  43 .Bd -literal
  44 typedef void (*task_fn_t)(void *context, int pending);
  45
  46 typedef void (*taskqueue_enqueue_fn)(void *context);
  47
  48 struct task {
  49         STAILQ_ENTRY(task)      ta_link;        /* link for queue */
  50         u_short                 ta_pending;     /* count times queued */
  51         u_short                 ta_priority;    /* priority of task in queue */
  52         task_fn_t               ta_func;        /* task handler */
  53         void                    *ta_context;    /* argument for handler */
  54 };
  55 .Ed
  56 .Ft struct taskqueue *
  57 .Fn taskqueue_create "const char *name" "int mflags" "taskqueue_enqueue_fn enqueue" "void *context" "struct proc **"
  58 .Ft void
  59 .Fn taskqueue_free "struct taskqueue *queue"
  60 .Ft struct taskqueue *
  61 .Fn taskqueue_find "const char *name"
  62 .Ft int
  63 .Fn taskqueue_enqueue "struct taskqueue *queue" "struct task *task"
  64 .Ft int
  65 .Fn taskqueue_enqueue_fast "struct taskqueue *queue" "struct task *task"
  66 .Ft void
  67 .Fn taskqueue_run "struct taskqueue *queue"
  68 .Ft void
  69 .Fn taskqueue_run_fast "struct taskqueue *queue"
  70 .Ft void
  71 .Fn taskqueue_drain "struct taskqueue *queue" "struct task *task"
  72 .Fn TASK_INIT "struct task *task" "int priority" "task_fn_t *func" "void *context"
  73 .Fn TASKQUEUE_DECLARE "name"
  74 .Fn TASKQUEUE_DEFINE "name" "taskqueue_enqueue_fn enqueue" "void *context" "init"
  75 .Fn TASKQUEUE_DEFINE_THREAD "name"
  76 .Sh DESCRIPTION
  77 These functions provide a simple interface for asynchronous execution
  78 of code.
  79 .Pp
  80 The function
  81 .Fn taskqueue_create
  82 is used to create new queues.
  83 The arguments to
  84 .Fn taskqueue_create
  85 include a name that should be unique,
  86 a set of
  87 .Xr malloc 9
  88 flags that specify whether the call to
  89 .Fn malloc
  90 is allowed to sleep,
  91 a function that is called from
  92 .Fn taskqueue_enqueue
  93 when a task is added to the queue,
  94 and a pointer to the memory location where the identity of the
  95 thread that services the queue is recorded.
  96 .\" XXX The rest of the sentence gets lots in relation to the first part.
  97 The function called from
  98 .Fn taskqueue_enqueue
  99 must arrange for the queue to be processed
 100 (for instance by scheduling a software interrupt or waking a kernel
 101 thread).
 102 The memory location where the thread identity is recorded is used
 103 to signal the service thread(s) to terminate--when this value is set to
 104 zero and the thread is signaled it will terminate.
 105 .Pp
 106 The function
 107 .Fn taskqueue_free
 108 should be used to remove the queue from the global list of queues
 109 and free the memory used by the queue.
 110 Any tasks that are on the queue will be executed at this time after
 111 which the thread servicing the queue will be signaled that it should exit.
 112 .Pp
 113 The system maintains a list of all queues which can be searched using
 114 .Fn taskqueue_find .
 115 The first queue whose name matches is returned, otherwise
 116 .Dv NULL .
 117 .Pp
 118 To add a task to the list of tasks queued on a taskqueue, call
 119 .Fn taskqueue_enqueue
 120 with pointers to the queue and task.
 121 If the task's
 122 .Va ta_pending
 123 field is non-zero,
 124 then it is simply incremented to reflect the number of times the task
 125 was enqueued.
 126 Otherwise,
 127 the task is added to the list before the first task which has a lower
 128 .Va ta_priority
 129 value or at the end of the list if no tasks have a lower priority.
 130 Enqueueing a task does not perform any memory allocation which makes
 131 it suitable for calling from an interrupt handler.
 132 This function will return
 133 .Er EPIPE
 134 if the queue is being freed.
 135 .Pp
 136 The function
 137 .Fn taskqueue_enqueue_fast
 138 should be used in place of
 139 .Fn taskqueue_enqueue
 140 when the enqueuing must happen from a fast interrupt handler.
 141 This method uses spin locks to avoid the possibility of sleeping in the fast
 142 interrupt context.
 143 .Pp
 144 To execute all the tasks on a queue,
 145 call
 146 .Fn taskqueue_run
 147 or
 148 .Fn taskqueue_run_fast
 149 depending on the flavour of the queue.
 150 When a task is executed,
 151 first it is removed from the queue,
 152 the value of
 153 .Va ta_pending
 154 is recorded and then the field is zeroed.
 155 The function
 156 .Va ta_func
 157 from the task structure is called with the value of the field
 158 .Va ta_context
 159 as its first argument
 160 and the value of
 161 .Va ta_pending
 162 as its second argument.
 163 After the function
 164 .Va ta_func
 165 returns,
 166 .Xr wakeup 9
 167 is called on the task pointer passed to
 168 .Fn taskqueue_enqueue .
 169 .Pp
 170 The
 171 .Fn taskqueue_drain
 172 function is used to wait for the task to finish.
 173 There is no guarantee that the task will not be
 174 enqueued after call to
 175 .Fn taskqueue_drain .
 176 .Pp
 177 A convenience macro,
 178 .Fn TASK_INIT "task" "priority" "func" "context"
 179 is provided to initialise a
 180 .Va task
 181 structure.
 182 The values of
 183 .Va priority ,
 184 .Va func ,
 185 and
 186 .Va context
 187 are simply copied into the task structure fields and the
 188 .Va ta_pending
 189 field is cleared.
 190 .Pp
 191 Three macros
 192 .Fn TASKQUEUE_DECLARE "name" ,
 193 .Fn TASKQUEUE_DEFINE "name" "enqueue" "context" "init" ,
 194 and
 195 .Fn TASKQUEUE_DEFINE_THREAD "name"
 196 are used to declare a reference to a global queue, to define the
 197 implementation of the queue, and declare a queue that uses its own thread.
 198 The
 199 .Fn TASKQUEUE_DEFINE
 200 macro arranges to call
 201 .Fn taskqueue_create
 202 with the values of its
 203 .Va name ,
 204 .Va enqueue
 205 and
 206 .Va context
 207 arguments during system initialisation.
 208 After calling
 209 .Fn taskqueue_create ,
 210 the
 211 .Va init
 212 argument to the macro is executed as a C statement,
 213 allowing any further initialisation to be performed
 214 (such as registering an interrupt handler etc.)
 215 .Pp
 216 The
 217 .Fn TASKQUEUE_DEFINE_THREAD
 218 macro defines a new taskqueue with its own kernel thread to serve tasks.
 219 The variable
 220 .Vt struct proc *taskqueue_name_proc
 221 is defined which contains the kernel thread serving the tasks.
 222 The variable
 223 .Vt struct taskqueue *taskqueue_name
 224 is used to enqueue tasks onto the queue.
 225 .Ss Predefined Task Queues
 226 The system provides four global taskqueues,
 227 .Va taskqueue_fast ,
 228 .Va taskqueue_swi ,
 229 .Va taskqueue_swi_giant ,
 230 and
 231 .Va taskqueue_thread .
 232 The
 233 .Va taskqueue_fast
 234 queue is for swi handlers dispatched from fast interrupt handlers,
 235 where sleep mutexes cannot be used.
 236 The swi taskqueues are run via a software interrupt mechanism.
 237 The
 238 .Va taskqueue_swi
 239 queue runs without the protection of the
 240 .Va Giant
 241 kernel lock, and the
 242 .Va taskqueue_swi_giant
 243 queue runs with the protection of the
 244 .Va Giant
 245 kernel lock.
 246 The thread taskqueue
 247 .Va taskqueue_thread
 248 runs in a kernel thread context, and tasks run from this thread do
 249 not run under the
 250 .Va Giant
 251 kernel lock.
 252 If the caller wants to run under
 253 .Va Giant ,
 254 he should explicitly acquire and release
 255 .Va Giant
 256 in his taskqueue handler routine.
 257 .Pp
 258 To use these queues,
 259 call
 260 .Fn taskqueue_enqueue
 261 with the value of the global taskqueue variable for the queue you wish to
 262 use
 263 .Va ( taskqueue_swi ,
 264 .Va taskqueue_swi_giant ,
 265 or
 266 .Va taskqueue_thread ) .
 267 Use
 268 .Fn taskqueue_enqueue_fast
 269 for the global taskqueue variable
 270 .Va taskqueue_fast .
 271 .Pp
 272 The software interrupt queues can be used,
 273 for instance, for implementing interrupt handlers which must perform a
 274 significant amount of processing in the handler.
 275 The hardware interrupt handler would perform minimal processing of the
 276 interrupt and then enqueue a task to finish the work.
 277 This reduces to a minimum
 278 the amount of time spent with interrupts disabled.
 279 .Pp
 280 The thread queue can be used, for instance, by interrupt level routines
 281 that need to call kernel functions that do things that can only be done
 282 from a thread context.
 283 (e.g., call malloc with the M_WAITOK flag.)
 284 .Pp
 285 Note that tasks queued on shared taskqueues such as
 286 .Va taskqueue_swi
 287 may be delayed an indeterminate amount of time before execution.
 288 If queueing delays cannot be tolerated then a private taskqueue should
 289 be created with a dedicated processing thread.
 290 .Sh SEE ALSO
 291 .Xr ithread 9 ,
 292 .Xr kthread 9 ,
 293 .Xr swi 9
 294 .Sh HISTORY
 295 This interface first appeared in
 296 .Fx 5.0 .
 297 There is a similar facility called tqueue in the Linux kernel.
 298 .Sh AUTHORS
 299 This manual page was written by
 300 .An Doug Rabson .
 301 .Sh BUGS
 302 There is no
 303 .Fn taskqueue_create_fast .