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