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 August 18, 2009
  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"
  58 .Ft struct taskqueue *
  59 .Fn taskqueue_create_fast "const char *name" "int mflags" "taskqueue_enqueue_fn enqueue" "void *context"
  60 .Ft void
  61 .Fn taskqueue_free "struct taskqueue *queue"
  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_drain "struct taskqueue *queue" "struct task *task"
  68 .Ft int
  69 .Fn taskqueue_member "struct taskqueue *queue" "struct thread *td"
  70 .Ft void
  71 .Fn taskqueue_run "struct taskqueue *queue"
  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_FAST_DEFINE "name" "taskqueue_enqueue_fn enqueue" "void *context" "init"
  76 .Fn TASKQUEUE_DEFINE_THREAD "name"
  77 .Fn TASKQUEUE_FAST_DEFINE_THREAD "name"
  78 .Sh DESCRIPTION
  79 These functions provide a simple interface for asynchronous execution
  80 of code.
  81 .Pp
  82 The function
  83 .Fn taskqueue_create
  84 is used to create new queues.
  85 The arguments to
  86 .Fn taskqueue_create
  87 include a name that should be unique,
  88 a set of
  89 .Xr malloc 9
  90 flags that specify whether the call to
  91 .Fn malloc
  92 is allowed to sleep,
  93 a function that is called from
  94 .Fn taskqueue_enqueue
  95 when a task is added to the queue,
  96 and a pointer to the memory location where the identity of the
  97 thread that services the queue is recorded.
  98 .\" XXX The rest of the sentence gets lots in relation to the first part.
  99 The function called from
 100 .Fn taskqueue_enqueue
 101 must arrange for the queue to be processed
 102 (for instance by scheduling a software interrupt or waking a kernel
 103 thread).
 104 The memory location where the thread identity is recorded is used
 105 to signal the service thread(s) to terminate--when this value is set to
 106 zero and the thread is signaled it will terminate.
 107 If the queue is intended for use in fast interrupt handlers
 108 .Fn taskqueue_create_fast
 109 should be used in place of
 110 .Fn taskqueue_create .
 111 .Pp
 112 The function
 113 .Fn taskqueue_free
 114 should be used to free the memory used by the queue.
 115 Any tasks that are on the queue will be executed at this time after
 116 which the thread servicing the queue will be signaled that it should exit.
 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 When a task is executed,
 145 first it is removed from the queue,
 146 the value of
 147 .Va ta_pending
 148 is recorded and then the field is zeroed.
 149 The function
 150 .Va ta_func
 151 from the task structure is called with the value of the field
 152 .Va ta_context
 153 as its first argument
 154 and the value of
 155 .Va ta_pending
 156 as its second argument.
 157 After the function
 158 .Va ta_func
 159 returns,
 160 .Xr wakeup 9
 161 is called on the task pointer passed to
 162 .Fn taskqueue_enqueue .
 163 .Pp
 164 The
 165 .Fn taskqueue_drain
 166 function is used to wait for the task to finish.
 167 There is no guarantee that the task will not be
 168 enqueued after call to
 169 .Fn taskqueue_drain .
 170 .Pp
 171 The
 172 .Fn taskqueue_member
 173 function returns
 174 .No 1
 175 if the given thread
 176 .Fa td
 177 is part of the given taskqueue
 178 .Fa queue
 179 and
 180 .No 0
 181 otherwise.
 182 .Pp
 183 The
 184 .Fn taskqueue_run
 185 function will run all pending tasks in the specified
 186 .Fa queue .
 187 Normally this function is only used internally.
 188 .Pp
 189 A convenience macro,
 190 .Fn TASK_INIT "task" "priority" "func" "context"
 191 is provided to initialise a
 192 .Va task
 193 structure.
 194 The values of
 195 .Va priority ,
 196 .Va func ,
 197 and
 198 .Va context
 199 are simply copied into the task structure fields and the
 200 .Va ta_pending
 201 field is cleared.
 202 .Pp
 203 Five macros
 204 .Fn TASKQUEUE_DECLARE "name" ,
 205 .Fn TASKQUEUE_DEFINE "name" "enqueue" "context" "init" ,
 206 .Fn TASKQUEUE_FAST_DEFINE "name" "enqueue" "context" "init" ,
 207 and
 208 .Fn TASKQUEUE_DEFINE_THREAD "name"
 209 .Fn TASKQUEUE_FAST_DEFINE_THREAD "name"
 210 are used to declare a reference to a global queue, to define the
 211 implementation of the queue, and declare a queue that uses its own thread.
 212 The
 213 .Fn TASKQUEUE_DEFINE
 214 macro arranges to call
 215 .Fn taskqueue_create
 216 with the values of its
 217 .Va name ,
 218 .Va enqueue
 219 and
 220 .Va context
 221 arguments during system initialisation.
 222 After calling
 223 .Fn taskqueue_create ,
 224 the
 225 .Va init
 226 argument to the macro is executed as a C statement,
 227 allowing any further initialisation to be performed
 228 (such as registering an interrupt handler etc.)
 229 .Pp
 230 The
 231 .Fn TASKQUEUE_DEFINE_THREAD
 232 macro defines a new taskqueue with its own kernel thread to serve tasks.
 233 The variable
 234 .Vt struct taskqueue *taskqueue_name
 235 is used to enqueue tasks onto the queue.
 236 .Pp
 237 .Fn TASKQUEUE_FAST_DEFINE
 238 and
 239 .Fn TASKQUEUE_FAST_DEFINE_THREAD
 240 act just like
 241 .Fn TASKQUEUE_DEFINE
 242 and
 243 .Fn TASKQUEUE_DEFINE_THREAD
 244 respectively but taskqueue is created with
 245 .Fn taskqueue_create_fast .
 246 .Ss Predefined Task Queues
 247 The system provides four global taskqueues,
 248 .Va taskqueue_fast ,
 249 .Va taskqueue_swi ,
 250 .Va taskqueue_swi_giant ,
 251 and
 252 .Va taskqueue_thread .
 253 The
 254 .Va taskqueue_fast
 255 queue is for swi handlers dispatched from fast interrupt handlers,
 256 where sleep mutexes cannot be used.
 257 The swi taskqueues are run via a software interrupt mechanism.
 258 The
 259 .Va taskqueue_swi
 260 queue runs without the protection of the
 261 .Va Giant
 262 kernel lock, and the
 263 .Va taskqueue_swi_giant
 264 queue runs with the protection of the
 265 .Va Giant
 266 kernel lock.
 267 The thread taskqueue
 268 .Va taskqueue_thread
 269 runs in a kernel thread context, and tasks run from this thread do
 270 not run under the
 271 .Va Giant
 272 kernel lock.
 273 If the caller wants to run under
 274 .Va Giant ,
 275 he should explicitly acquire and release
 276 .Va Giant
 277 in his taskqueue handler routine.
 278 .Pp
 279 To use these queues,
 280 call
 281 .Fn taskqueue_enqueue
 282 with the value of the global taskqueue variable for the queue you wish to
 283 use
 284 .Va ( taskqueue_swi ,
 285 .Va taskqueue_swi_giant ,
 286 or
 287 .Va taskqueue_thread ) .
 288 Use
 289 .Fn taskqueue_enqueue_fast
 290 for the global taskqueue variable
 291 .Va taskqueue_fast .
 292 .Pp
 293 The software interrupt queues can be used,
 294 for instance, for implementing interrupt handlers which must perform a
 295 significant amount of processing in the handler.
 296 The hardware interrupt handler would perform minimal processing of the
 297 interrupt and then enqueue a task to finish the work.
 298 This reduces to a minimum
 299 the amount of time spent with interrupts disabled.
 300 .Pp
 301 The thread queue can be used, for instance, by interrupt level routines
 302 that need to call kernel functions that do things that can only be done
 303 from a thread context.
 304 (e.g., call malloc with the M_WAITOK flag.)
 305 .Pp
 306 Note that tasks queued on shared taskqueues such as
 307 .Va taskqueue_swi
 308 may be delayed an indeterminate amount of time before execution.
 309 If queueing delays cannot be tolerated then a private taskqueue should
 310 be created with a dedicated processing thread.
 311 .Sh SEE ALSO
 312 .Xr ithread 9 ,
 313 .Xr kthread 9 ,
 314 .Xr swi 9
 315 .Sh HISTORY
 316 This interface first appeared in
 317 .Fx 5.0 .
 318 There is a similar facility called tqueue in the Linux kernel.
 319 .Sh AUTHORS
 320 This manual page was written by
 321 .An Doug Rabson .