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