share/man/man9/taskqueue.9

   1 .\"
   2 .\" Copyright (c) 2000 Doug Rabson
   3 .\"
   4 .\" All rights reserved.
   5 .\"
   6 .\" This program is free software.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\" 2. Redistributions in binary form must reproduce the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer in the
  15 .\"    documentation and/or other materials provided with the distribution.
  16 .\"
  17 .\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
  18 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  19 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  20 .\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
  21 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  22 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  23 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  24 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  25 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  26 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  27 .\"
  28 .\" $FreeBSD: src/share/man/man9/taskqueue.9,v 1.21 2007/07/09 06:24:10 jmg Exp $
  29 .\" $DragonFly: src/share/man/man9/taskqueue.9,v 1.2 2007/11/07 21:38:00 swildner Exp $
  30 .\"
  31 .Dd August 10, 2007
  32 .Dt TASKQUEUE 9
  33 .Os
  34 .Sh NAME
  35 .Nm taskqueue_create ,
  36 .Nm taskqueue_free ,
  37 .Nm taskqueue_find ,
  38 .Nm taskqueue_enqueue ,
  39 .Nm taskqueue_run ,
  40 .Nm TASK_INIT ,
  41 .Nm TASKQUEUE_DECLARE ,
  42 .Nm TASKQUEUE_DEFINE
  43 .Nd asynchronous task execution
  44 .Sh SYNOPSIS
  45 .In sys/param.h
  46 .In sys/kernel.h
  47 .In sys/malloc.h
  48 .In sys/queue.h
  49 .In sys/taskqueue.h
  50 .Bd -literal
  51 typedef void (*task_fn_t)(void *context, int pending);
  52
  53 typedef void (*taskqueue_enqueue_fn)(void *context);
  54
  55 struct task {
  56         STAILQ_ENTRY(task)      ta_link;        /* link for queue */
  57         int                     ta_pending;     /* count times queued */
  58         int                     ta_priority;    /* priority of task in queue */
  59         task_fn_t               ta_func;        /* task handler */
  60         void                    *ta_context;    /* argument for handler */
  61 };
  62 .Ed
  63 .Ft struct taskqueue *
  64 .Fn taskqueue_create "const char *name" "int mflags" "taskqueue_enqueue_fn enqueue" "void *context"
  65 .Ft void
  66 .Fn taskqueue_free "struct taskqueue *queue"
  67 .Ft struct taskqueue *
  68 .Fn taskqueue_find "const char *name"
  69 .Ft int
  70 .Fn taskqueue_enqueue "struct taskqueue *queue" "struct task *task"
  71 .Ft void
  72 .Fn taskqueue_run "struct taskqueue *queue"
  73 .Fn TASK_INIT "struct task *task" "int priority" "task_fn_t *func" "void *context"
  74 .Fn TASKQUEUE_DECLARE "name"
  75 .Fn TASKQUEUE_DEFINE "name" "taskqueue_enqueue_fn enqueue" "void *context" "init"
  76 .Sh DESCRIPTION
  77 These functions provide a simple interface for asynchronous execution
  78 of code.
  79 .Pp
  80 The function
  81 .Fn taskqueue_create
  82 is used to create new queues.
  83 The arguments to
  84 .Fn taskqueue_create
  85 include a name that should be unique,
  86 a set of
  87 .Xr kmalloc 9
  88 flags that specify whether the call to
  89 .Fn malloc
  90 is allowed to sleep,
  91 and a function which is called from
  92 .Fn taskqueue_enqueue
  93 when a task is added to the queue
  94 .\" XXX The rest of the sentence gets lots in relation to the first part.
  95 to allow the queue to arrange to be run later
  96 (for instance by scheduling a software interrupt or waking a kernel
  97 thread).
  98 .Pp
  99 The function
 100 .Fn taskqueue_free
 101 should be used to remove the queue from the global list of queues
 102 and free the memory used by the queue.
 103 Any tasks that are on the queue will be executed at this time.
 104 .Pp
 105 The system maintains a list of all queues which can be searched using
 106 .Fn taskqueue_find .
 107 The first queue whose name matches is returned, otherwise
 108 .Dv NULL .
 109 .Pp
 110 To add a task to the list of tasks queued on a taskqueue, call
 111 .Fn taskqueue_enqueue
 112 with pointers to the queue and task.
 113 If the task's
 114 .Fa ta_pending
 115 field is non-zero,
 116 then it is simply incremented to reflect the number of times the task
 117 was enqueued.
 118 Otherwise,
 119 the task is added to the list before the first task which has a lower
 120 .Fa ta_priority
 121 value or at the end of the list if no tasks have a lower priority.
 122 Enqueueing a task does not perform any memory allocation which makes
 123 it suitable for calling from an interrupt handler.
 124 This function will return
 125 .Er EPIPE
 126 if the queue is being freed.
 127 .Pp
 128 To execute all the tasks on a queue,
 129 call
 130 .Fn taskqueue_run .
 131 When a task is executed,
 132 first it is removed from the queue,
 133 the value of
 134 .Fa ta_pending
 135 is recorded and then the field is zeroed.
 136 The function
 137 .Fa ta_func
 138 from the task structure is called with the value of the field
 139 .Fa ta_context
 140 as its first argument
 141 and the value of
 142 .Fa ta_pending
 143 as its second argument.
 144 .Pp
 145 A convenience macro,
 146 .Fn TASK_INIT
 147 is provided to initialise a
 148 .Vt task
 149 structure.
 150 The values of
 151 .Fa priority ,
 152 .Fa func ,
 153 and
 154 .Fa context
 155 are simply copied into the task structure fields and the
 156 .Fa ta_pending
 157 field is cleared.
 158 .Pp
 159 Two macros,
 160 .Fn TASKQUEUE_DECLARE
 161 and
 162 .Fn TASKQUEUE_DEFINE
 163 are used to declare a reference to a global queue,
 164 and to define the implementation of the queue.
 165 The
 166 .Fn TASKQUEUE_DEFINE
 167 macro arranges to call
 168 .Fn taskqueue_create
 169 with the values of its
 170 .Fa name ,
 171 .Fa enqueue
 172 and
 173 .Fa context
 174 arguments during system initialisation.
 175 After calling
 176 .Fn taskqueue_create ,
 177 the
 178 .Fa init
 179 argument to the macro is executed as a C statement,
 180 allowing any further initialisation to be performed
 181 (such as registering an interrupt handler etc.)
 182 .Pp
 183 The system provides a global taskqueue,
 184 .Va taskqueue_swi ,
 185 which is run via a software interrupt mechanism.
 186 To use this queue, call
 187 .Fn taskqueue_enqueue
 188 with the value of the global variable
 189 .Va taskqueue_swi .
 190 .Pp
 191 This queue can be used,
 192 for instance, for implementing interrupt handlers which must perform a
 193 significant amount of processing in the handler.
 194 The hardware interrupt handler would perform minimal processing of the
 195 interrupt and then enqueue a task to finish the work.
 196 This reduces to a minimum
 197 the amount of time spent with interrupts disabled.
 198 .\".Sh SEE ALSO
 199 .\".Xr ithread 9 ,
 200 .\".Xr kthread 9 ,
 201 .\".Xr swi 9
 202 .Sh HISTORY
 203 This interface first appeared in
 204 .Fx 5.0 .
 205 There is a similar facility called tqueue in the Linux kernel.
 206 .Sh AUTHORS
 207 This manual page was written by
 208 .An Doug Rabson .