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 .Pp
 225 The
 226 .Fn taskqueue_cancel
 227 function is used to cancel a task.
 228 The
 229 .Va ta_pending
 230 count is cleared, and the old value returned in the reference
 231 parameter
 232 .Fa pendp ,
 233 if it is
 234 .Pf non- Dv NULL .
 235 If the task is currently running,
 236 .Dv EBUSY
 237 is returned, otherwise 0.
 238 To implement a blocking
 239 .Fn taskqueue_cancel
 240 that waits for a running task to finish, it could look like:
 241 .Bd -literal -offset indent
 242 while (taskqueue_cancel(tq, task, NULL) != 0)
 243         taskqueue_drain(tq, task);
 244 .Ed
 245 .Pp
 246 Note that, as with
 247 .Fn taskqueue_drain ,
 248 the caller is responsible for ensuring that the task is not re-enqueued
 249 after being canceled.
 250 .Pp
 251 Similarly, the
 252 .Fn taskqueue_cancel_timeout
 253 function is used to cancel the scheduled task execution.
 254 .Pp
 255 The
 256 .Fn taskqueue_drain
 257 function is used to wait for the task to finish, and
 258 the
 259 .Fn taskqueue_drain_timeout
 260 function is used to wait for the scheduled task to finish.
 261 There is no guarantee that the task will not be
 262 enqueued after call to
 263 .Fn taskqueue_drain .
 264 If the caller wants to put the task into a known state,
 265 then before calling
 266 .Fn taskqueue_drain
 267 the caller should use out-of-band means to ensure that the task
 268 would not be enqueued.
 269 For example, if the task is enqueued by an interrupt filter, then
 270 the interrupt could be disabled.
 271 .Pp
 272 The
 273 .Fn taskqueue_drain_all
 274 function is used to wait for all pending and running tasks that
 275 are enqueued on the taskqueue to finish.
 276 The caller must arrange that the tasks are not re-enqueued.
 277 Note that
 278 .Fn taskqueue_drain_all
 279 currently does not handle tasks with delayed enqueueing.
 280 .Pp
 281 The
 282 .Fn taskqueue_block
 283 function blocks the taskqueue.
 284 It prevents any enqueued but not running tasks from being executed.
 285 Future calls to
 286 .Fn taskqueue_enqueue
 287 will enqueue tasks, but the tasks will not be run until
 288 .Fn taskqueue_unblock
 289 is called.
 290 Please note that
 291 .Fn taskqueue_block
 292 does not wait for any currently running tasks to finish.
 293 Thus, the
 294 .Fn taskqueue_block
 295 does not provide a guarantee that
 296 .Fn taskqueue_run
 297 is not running after
 298 .Fn taskqueue_block
 299 returns, but it does provide a guarantee that
 300 .Fn taskqueue_run
 301 will not be called again
 302 until
 303 .Fn taskqueue_unblock
 304 is called.
 305 If the caller requires a guarantee that
 306 .Fn taskqueue_run
 307 is not running, then this must be arranged by the caller.
 308 Note that if
 309 .Fn taskqueue_drain
 310 is called on a task that is enqueued on a taskqueue that is blocked by
 311 .Fn taskqueue_block ,
 312 then
 313 .Fn taskqueue_drain
 314 can not return until the taskqueue is unblocked.
 315 This can result in a deadlock if the thread blocked in
 316 .Fn taskqueue_drain
 317 is the thread that is supposed to call
 318 .Fn taskqueue_unblock .
 319 Thus, use of
 320 .Fn taskqueue_drain
 321 after
 322 .Fn taskqueue_block
 323 is discouraged, because the state of the task can not be known in advance.
 324 The same caveat applies to
 325 .Fn taskqueue_drain_all .
 326 .Pp
 327 The
 328 .Fn taskqueue_unblock
 329 function unblocks the previously blocked taskqueue.
 330 All enqueued tasks can be run after this call.
 331 .Pp
 332 The
 333 .Fn taskqueue_member
 334 function returns
 335 .No 1
 336 if the given thread
 337 .Fa td
 338 is part of the given taskqueue
 339 .Fa queue
 340 and
 341 .No 0
 342 otherwise.
 343 .Pp
 344 The
 345 .Fn taskqueue_run
 346 function will run all pending tasks in the specified
 347 .Fa queue .
 348 Normally this function is only used internally.
 349 .Pp
 350 A convenience macro,
 351 .Fn TASK_INIT "task" "priority" "func" "context"
 352 is provided to initialise a
 353 .Va task
 354 structure.
 355 The
 356 .Fn TASK_INITIALIZER
 357 macro generates an initializer for a task structure.
 358 A macro
 359 .Fn TIMEOUT_TASK_INIT "queue" "timeout_task" "priority" "func" "context"
 360 initializes the
 361 .Va timeout_task
 362 structure.
 363 The values of
 364 .Va priority ,
 365 .Va func ,
 366 and
 367 .Va context
 368 are simply copied into the task structure fields and the
 369 .Va ta_pending
 370 field is cleared.
 371 .Pp
 372 Five macros
 373 .Fn TASKQUEUE_DECLARE "name" ,
 374 .Fn TASKQUEUE_DEFINE "name" "enqueue" "context" "init" ,
 375 .Fn TASKQUEUE_FAST_DEFINE "name" "enqueue" "context" "init" ,
 376 and
 377 .Fn TASKQUEUE_DEFINE_THREAD "name"
 378 .Fn TASKQUEUE_FAST_DEFINE_THREAD "name"
 379 are used to declare a reference to a global queue, to define the
 380 implementation of the queue, and declare a queue that uses its own thread.
 381 The
 382 .Fn TASKQUEUE_DEFINE
 383 macro arranges to call
 384 .Fn taskqueue_create
 385 with the values of its
 386 .Va name ,
 387 .Va enqueue
 388 and
 389 .Va context
 390 arguments during system initialisation.
 391 After calling
 392 .Fn taskqueue_create ,
 393 the
 394 .Va init
 395 argument to the macro is executed as a C statement,
 396 allowing any further initialisation to be performed
 397 (such as registering an interrupt handler etc.)
 398 .Pp
 399 The
 400 .Fn TASKQUEUE_DEFINE_THREAD
 401 macro defines a new taskqueue with its own kernel thread to serve tasks.
 402 The variable
 403 .Vt struct taskqueue *taskqueue_name
 404 is used to enqueue tasks onto the queue.
 405 .Pp
 406 .Fn TASKQUEUE_FAST_DEFINE
 407 and
 408 .Fn TASKQUEUE_FAST_DEFINE_THREAD
 409 act just like
 410 .Fn TASKQUEUE_DEFINE
 411 and
 412 .Fn TASKQUEUE_DEFINE_THREAD
 413 respectively but taskqueue is created with
 414 .Fn taskqueue_create_fast .
 415 .Ss Predefined Task Queues
 416 The system provides four global taskqueues,
 417 .Va taskqueue_fast ,
 418 .Va taskqueue_swi ,
 419 .Va taskqueue_swi_giant ,
 420 and
 421 .Va taskqueue_thread .
 422 The
 423 .Va taskqueue_fast
 424 queue is for swi handlers dispatched from fast interrupt handlers,
 425 where sleep mutexes cannot be used.
 426 The swi taskqueues are run via a software interrupt mechanism.
 427 The
 428 .Va taskqueue_swi
 429 queue runs without the protection of the
 430 .Va Giant
 431 kernel lock, and the
 432 .Va taskqueue_swi_giant
 433 queue runs with the protection of the
 434 .Va Giant
 435 kernel lock.
 436 The thread taskqueue
 437 .Va taskqueue_thread
 438 runs in a kernel thread context, and tasks run from this thread do
 439 not run under the
 440 .Va Giant
 441 kernel lock.
 442 If the caller wants to run under
 443 .Va Giant ,
 444 he should explicitly acquire and release
 445 .Va Giant
 446 in his taskqueue handler routine.
 447 .Pp
 448 To use these queues,
 449 call
 450 .Fn taskqueue_enqueue
 451 with the value of the global taskqueue variable for the queue you wish to
 452 use
 453 .Va ( taskqueue_swi ,
 454 .Va taskqueue_swi_giant ,
 455 or
 456 .Va taskqueue_thread ) .
 457 Use
 458 .Fn taskqueue_enqueue_fast
 459 for the global taskqueue variable
 460 .Va taskqueue_fast .
 461 .Pp
 462 The software interrupt queues can be used,
 463 for instance, for implementing interrupt handlers which must perform a
 464 significant amount of processing in the handler.
 465 The hardware interrupt handler would perform minimal processing of the
 466 interrupt and then enqueue a task to finish the work.
 467 This reduces to a minimum
 468 the amount of time spent with interrupts disabled.
 469 .Pp
 470 The thread queue can be used, for instance, by interrupt level routines
 471 that need to call kernel functions that do things that can only be done
 472 from a thread context.
 473 (e.g., call malloc with the M_WAITOK flag.)
 474 .Pp
 475 Note that tasks queued on shared taskqueues such as
 476 .Va taskqueue_swi
 477 may be delayed an indeterminate amount of time before execution.
 478 If queueing delays cannot be tolerated then a private taskqueue should
 479 be created with a dedicated processing thread.
 480 .Sh SEE ALSO
 481 .Xr ithread 9 ,
 482 .Xr kthread 9 ,
 483 .Xr swi 9
 484 .Sh HISTORY
 485 This interface first appeared in
 486 .Fx 5.0 .
 487 There is a similar facility called work_queue in the Linux kernel.
 488 .Sh AUTHORS
 489 This manual page was written by
 490 .An Doug Rabson .