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