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