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