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 April 26, 2011
  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
  56 struct timeout_task;
  57 .Ed
  58 .Ft struct taskqueue *
  59 .Fn taskqueue_create "const char *name" "int mflags" "taskqueue_enqueue_fn enqueue" "void *context"
  60 .Ft struct taskqueue *
  61 .Fn taskqueue_create_fast "const char *name" "int mflags" "taskqueue_enqueue_fn enqueue" "void *context"
  62 .Ft void
  63 .Fn taskqueue_free "struct taskqueue *queue"
  64 .Ft int
  65 .Fn taskqueue_enqueue "struct taskqueue *queue" "struct task *task"
  66 .Ft int
  67 .Fn taskqueue_enqueue_fast "struct taskqueue *queue" "struct task *task"
  68 .Ft int
  69 .Fn taskqueue_enqueue_timeout "struct taskqueue *queue" "struct timeout_task *timeout_task" "int ticks"
  70 .Ft int
  71 .Fn taskqueue_cancel "struct taskqueue *queue" "struct task *task" "u_int *pendp"
  72 .Ft int
  73 .Fn taskqueue_cancel_timeout "struct taskqueue *queue" "struct timeout_task *timeout_task" "u_int *pendp"
  74 .Ft void
  75 .Fn taskqueue_drain "struct taskqueue *queue" "struct task *task"
  76 .Ft void
  77 .Fn taskqueue_drain_timeout "struct taskqueue *queue" "struct timeout_task *timeout_task"
  78 .Ft int
  79 .Fn taskqueue_member "struct taskqueue *queue" "struct thread *td"
  80 .Ft void
  81 .Fn taskqueue_run "struct taskqueue *queue"
  82 .Fn TASK_INIT "struct task *task" "int priority" "task_fn_t func" "void *context"
  83 .Fn TASK_INITIALIZER "int priority" "task_fn_t func" "void *context"
  84 .Fn TASKQUEUE_DECLARE "name"
  85 .Fn TASKQUEUE_DEFINE "name" "taskqueue_enqueue_fn enqueue" "void *context" "init"
  86 .Fn TASKQUEUE_FAST_DEFINE "name" "taskqueue_enqueue_fn enqueue" "void *context" "init"
  87 .Fn TASKQUEUE_DEFINE_THREAD "name"
  88 .Fn TASKQUEUE_FAST_DEFINE_THREAD "name"
  89 .Fn TIMEOUT_TASK_INIT "struct taskqueue *queue" "struct timeout_task *timeout_task" "int priority" "task_fn_t func" "void *context"
  90 .Sh DESCRIPTION
  91 These functions provide a simple interface for asynchronous execution
  92 of code.
  93 .Pp
  94 The function
  95 .Fn taskqueue_create
  96 is used to create new queues.
  97 The arguments to
  98 .Fn taskqueue_create
  99 include a name that should be unique,
 100 a set of
 101 .Xr malloc 9
 102 flags that specify whether the call to
 103 .Fn malloc
 104 is allowed to sleep,
 105 a function that is called from
 106 .Fn taskqueue_enqueue
 107 when a task is added to the queue,
 108 and a pointer to the memory location where the identity of the
 109 thread that services the queue is recorded.
 110 .\" XXX The rest of the sentence gets lots in relation to the first part.
 111 The function called from
 112 .Fn taskqueue_enqueue
 113 must arrange for the queue to be processed
 114 (for instance by scheduling a software interrupt or waking a kernel
 115 thread).
 116 The memory location where the thread identity is recorded is used
 117 to signal the service thread(s) to terminate--when this value is set to
 118 zero and the thread is signaled it will terminate.
 119 If the queue is intended for use in fast interrupt handlers
 120 .Fn taskqueue_create_fast
 121 should be used in place of
 122 .Fn taskqueue_create .
 123 .Pp
 124 The function
 125 .Fn taskqueue_free
 126 should be used to free the memory used by the queue.
 127 Any tasks that are on the queue will be executed at this time after
 128 which the thread servicing the queue will be signaled that it should exit.
 129 .Pp
 130 To add a task to the list of tasks queued on a taskqueue, call
 131 .Fn taskqueue_enqueue
 132 with pointers to the queue and task.
 133 If the task's
 134 .Va ta_pending
 135 field is non-zero,
 136 then it is simply incremented to reflect the number of times the task
 137 was enqueued, up to a cap of USHRT_MAX.
 138 Otherwise,
 139 the task is added to the list before the first task which has a lower
 140 .Va ta_priority
 141 value or at the end of the list if no tasks have a lower priority.
 142 Enqueueing a task does not perform any memory allocation which makes
 143 it suitable for calling from an interrupt handler.
 144 This function will return
 145 .Er EPIPE
 146 if the queue is being freed.
 147 .Pp
 148 The function
 149 .Fn taskqueue_enqueue_fast
 150 should be used in place of
 151 .Fn taskqueue_enqueue
 152 when the enqueuing must happen from a fast interrupt handler.
 153 This method uses spin locks to avoid the possibility of sleeping in the fast
 154 interrupt context.
 155 .Pp
 156 When a task is executed,
 157 first it is removed from the queue,
 158 the value of
 159 .Va ta_pending
 160 is recorded and then the field is zeroed.
 161 The function
 162 .Va ta_func
 163 from the task structure is called with the value of the field
 164 .Va ta_context
 165 as its first argument
 166 and the value of
 167 .Va ta_pending
 168 as its second argument.
 169 After the function
 170 .Va ta_func
 171 returns,
 172 .Xr wakeup 9
 173 is called on the task pointer passed to
 174 .Fn taskqueue_enqueue .
 175 .Pp
 176 The
 177 .Fn taskqueue_enqueue_timeout
 178 is used to schedule the enqueue after the specified amount of
 179 .Va ticks .
 180 Only non-fast task queues can be used for
 181 .Va timeout_task
 182 scheduling.
 183 .Pp
 184 The
 185 .Fn taskqueue_cancel
 186 function is used to cancel a task.
 187 The
 188 .Va ta_pending
 189 count is cleared, and the old value returned in the reference
 190 parameter
 191 .Fa pendp ,
 192 if it is
 193 .Pf non- Dv NULL .
 194 If the task is currently running,
 195 .Dv EBUSY
 196 is returned, otherwise 0.
 197 To implement a blocking
 198 .Fn taskqueue_cancel
 199 that waits for a running task to finish, it could look like:
 200 .Bd -literal -offset indent
 201 while (taskqueue_cancel(tq, task, NULL) != 0)
 202         taskqueue_drain(tq, task);
 203 .Ed
 204 .Pp
 205 Note that, as with
 206 .Fn taskqueue_drain ,
 207 the caller is responsible for ensuring that the task is not re-enqueued
 208 after being canceled.
 209 .Pp
 210 Similarly, the
 211 .Fn taskqueue_cancel_timeout
 212 function is used to cancel the scheduled task execution.
 213 .Pp
 214 The
 215 .Fn taskqueue_drain
 216 function is used to wait for the task to finish, and
 217 the
 218 .Fn taskqueue_drain_timeout
 219 function is used to wait for the scheduled task to finish.
 220 There is no guarantee that the task will not be
 221 enqueued after call to
 222 .Fn taskqueue_drain .
 223 .Pp
 224 The
 225 .Fn taskqueue_member
 226 function returns
 227 .No 1
 228 if the given thread
 229 .Fa td
 230 is part of the given taskqueue
 231 .Fa queue
 232 and
 233 .No 0
 234 otherwise.
 235 .Pp
 236 The
 237 .Fn taskqueue_run
 238 function will run all pending tasks in the specified
 239 .Fa queue .
 240 Normally this function is only used internally.
 241 .Pp
 242 A convenience macro,
 243 .Fn TASK_INIT "task" "priority" "func" "context"
 244 is provided to initialise a
 245 .Va task
 246 structure.
 247 The
 248 .Fn TASK_INITIALIZER
 249 macro generates an initializer for a task structure.
 250 A macro
 251 .Fn TIMEOUT_TASK_INIT "queue" "timeout_task" "priority" "func" "context"
 252 initializes the
 253 .Va timeout_task
 254 structure.
 255 The values of
 256 .Va priority ,
 257 .Va func ,
 258 and
 259 .Va context
 260 are simply copied into the task structure fields and the
 261 .Va ta_pending
 262 field is cleared.
 263 .Pp
 264 Five macros
 265 .Fn TASKQUEUE_DECLARE "name" ,
 266 .Fn TASKQUEUE_DEFINE "name" "enqueue" "context" "init" ,
 267 .Fn TASKQUEUE_FAST_DEFINE "name" "enqueue" "context" "init" ,
 268 and
 269 .Fn TASKQUEUE_DEFINE_THREAD "name"
 270 .Fn TASKQUEUE_FAST_DEFINE_THREAD "name"
 271 are used to declare a reference to a global queue, to define the
 272 implementation of the queue, and declare a queue that uses its own thread.
 273 The
 274 .Fn TASKQUEUE_DEFINE
 275 macro arranges to call
 276 .Fn taskqueue_create
 277 with the values of its
 278 .Va name ,
 279 .Va enqueue
 280 and
 281 .Va context
 282 arguments during system initialisation.
 283 After calling
 284 .Fn taskqueue_create ,
 285 the
 286 .Va init
 287 argument to the macro is executed as a C statement,
 288 allowing any further initialisation to be performed
 289 (such as registering an interrupt handler etc.)
 290 .Pp
 291 The
 292 .Fn TASKQUEUE_DEFINE_THREAD
 293 macro defines a new taskqueue with its own kernel thread to serve tasks.
 294 The variable
 295 .Vt struct taskqueue *taskqueue_name
 296 is used to enqueue tasks onto the queue.
 297 .Pp
 298 .Fn TASKQUEUE_FAST_DEFINE
 299 and
 300 .Fn TASKQUEUE_FAST_DEFINE_THREAD
 301 act just like
 302 .Fn TASKQUEUE_DEFINE
 303 and
 304 .Fn TASKQUEUE_DEFINE_THREAD
 305 respectively but taskqueue is created with
 306 .Fn taskqueue_create_fast .
 307 .Ss Predefined Task Queues
 308 The system provides four global taskqueues,
 309 .Va taskqueue_fast ,
 310 .Va taskqueue_swi ,
 311 .Va taskqueue_swi_giant ,
 312 and
 313 .Va taskqueue_thread .
 314 The
 315 .Va taskqueue_fast
 316 queue is for swi handlers dispatched from fast interrupt handlers,
 317 where sleep mutexes cannot be used.
 318 The swi taskqueues are run via a software interrupt mechanism.
 319 The
 320 .Va taskqueue_swi
 321 queue runs without the protection of the
 322 .Va Giant
 323 kernel lock, and the
 324 .Va taskqueue_swi_giant
 325 queue runs with the protection of the
 326 .Va Giant
 327 kernel lock.
 328 The thread taskqueue
 329 .Va taskqueue_thread
 330 runs in a kernel thread context, and tasks run from this thread do
 331 not run under the
 332 .Va Giant
 333 kernel lock.
 334 If the caller wants to run under
 335 .Va Giant ,
 336 he should explicitly acquire and release
 337 .Va Giant
 338 in his taskqueue handler routine.
 339 .Pp
 340 To use these queues,
 341 call
 342 .Fn taskqueue_enqueue
 343 with the value of the global taskqueue variable for the queue you wish to
 344 use
 345 .Va ( taskqueue_swi ,
 346 .Va taskqueue_swi_giant ,
 347 or
 348 .Va taskqueue_thread ) .
 349 Use
 350 .Fn taskqueue_enqueue_fast
 351 for the global taskqueue variable
 352 .Va taskqueue_fast .
 353 .Pp
 354 The software interrupt queues can be used,
 355 for instance, for implementing interrupt handlers which must perform a
 356 significant amount of processing in the handler.
 357 The hardware interrupt handler would perform minimal processing of the
 358 interrupt and then enqueue a task to finish the work.
 359 This reduces to a minimum
 360 the amount of time spent with interrupts disabled.
 361 .Pp
 362 The thread queue can be used, for instance, by interrupt level routines
 363 that need to call kernel functions that do things that can only be done
 364 from a thread context.
 365 (e.g., call malloc with the M_WAITOK flag.)
 366 .Pp
 367 Note that tasks queued on shared taskqueues such as
 368 .Va taskqueue_swi
 369 may be delayed an indeterminate amount of time before execution.
 370 If queueing delays cannot be tolerated then a private taskqueue should
 371 be created with a dedicated processing thread.
 372 .Sh SEE ALSO
 373 .Xr ithread 9 ,
 374 .Xr kthread 9 ,
 375 .Xr swi 9
 376 .Sh HISTORY
 377 This interface first appeared in
 378 .Fx 5.0 .
 379 There is a similar facility called work_queue in the Linux kernel.
 380 .Sh AUTHORS
 381 This manual page was written by
 382 .An Doug Rabson .