share/man/man9/workqueue.9

   1 .\"     $NetBSD: workqueue.9,v 1.7 2009/08/03 23:29:19 rmind Exp $
   2 .\"
   3 .\" Copyright (c)2005 YAMAMOTO Takashi,
   4 .\" All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\"
  15 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  16 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  17 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  18 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  19 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  20 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  21 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  22 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  23 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  24 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  25 .\" SUCH DAMAGE.
  26 .\"
  27 .\" ------------------------------------------------------------
  28 .Dd August 3, 2009
  29 .Dt WORKQUEUE 9
  30 .Os
  31 .\" ------------------------------------------------------------
  32 .Sh NAME
  33 .Nm workqueue
  34 .Nd simple do-it-in-thread-context framework
  35 .\" ------------------------------------------------------------
  36 .Sh SYNOPSIS
  37 .In sys/workqueue.h
  38 .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  39 .Ft int
  40 .Fn workqueue_create \
  41 "struct workqueue **wqp" "const char *name" \
  42 "void (*func)(struct work *, void *)" "void *arg" \
  43 "pri_t prio" "int ipl" "int flags"
  44 .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  45 .Ft void
  46 .Fn workqueue_enqueue \
  47 "struct workqueue *wq" "struct work *wk" "struct cpu_info *ci"
  48 .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  49 .Ft void
  50 .Fn workqueue_destroy \
  51 "struct workqueue *wq"
  52 .\" ------------------------------------------------------------
  53 .Sh DESCRIPTION
  54 The
  55 .Nm
  56 utility routines are provided to defer work which is needed to be
  57 processed in a thread context.
  58 .Pp
  59 .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  60 .Fn workqueue_create
  61 creates a workqueue.
  62 It takes the following arguments:
  63 .Bl -tag -width flags
  64 .It Fa wqp
  65 Specify where to store the created workqueue.
  66 .It Fa name
  67 The name of the workqueue.
  68 .It Fa func
  69 The function to be called for each
  70 .Fa work .
  71 .It Fa arg
  72 An argument to be passed as a second argument of
  73 .Fa func .
  74 .It Fa prio
  75 The process priority to be used when sleeping to wait requests.
  76 .It Fa ipl
  77 The highest IPL at which this workqueue is used.
  78 .It Fa flags
  79 The value of 0 indicates a standard create operation, however the following
  80 flags may be bitwise ORed together:
  81 .Bl -tag -width WQ_MPSAFE
  82 .It Dv WQ_MPSAFE
  83 Specifies that the workqueue is multiprocessor safe and does its own locking,
  84 otherwise the kernel lock will be held while work will be processed.
  85 .It Dv WQ_PERCPU
  86 Specifies that the workqueue should have a separate queue for each CPU,
  87 thus the work could be enqueued on concrete CPUs.
  88 .El
  89 .El
  90 .Pp
  91 .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  92 .Fn workqueue_enqueue
  93 enqueues the work
  94 .Fa wk
  95 into the workqueue
  96 .Fa wq .
  97 .Pp
  98 If the
  99 .Dv WQ_PERCPU
 100 flag was set on workqueue creation, the
 101 .Fa ci
 102 argument may be used to specify the CPU on which the work should
 103 be enqueued.
 104 Also it may be
 105 .Dv NULL ,
 106 then work will be enqueued on the current CPU.
 107 If
 108 .Dv WQ_PERCPU
 109 flag was not set,
 110 .Fa ci
 111 must be
 112 .Dv NULL .
 113 .Pp
 114 The enqueued work will be processed in a thread context.
 115 A work must not be enqueued again until the callback is called by
 116 the
 117 .Nm
 118 framework.
 119 .Pp
 120 .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 121 .Fn workqueue_destroy
 122 destroys a workqueue and frees associated resources.
 123 The caller should ensure that the workqueue has no work enqueued beforehand.
 124 .\" ------------------------------------------------------------
 125 .Sh RETURN VALUES
 126 .Fn workqueue_create
 127 returns 0 on success.
 128 Otherwise, it returns an
 129 .Xr errno 2 .
 130 .\" ------------------------------------------------------------
 131 .Sh CODE REFERENCES
 132 This section describes places within the
 133 .Nx
 134 source tree where actual code implementing the
 135 .Nm
 136 subsystem
 137 can be found.
 138 All pathnames are relative to
 139 .Pa /usr/src .
 140 .Pp
 141 The
 142 .Nm
 143 subsystem is implemented within the file
 144 .Pa sys/kern/subr_workqueue.c .
 145 .\" ------------------------------------------------------------
 146 .Sh SEE ALSO
 147 .Xr callout 9 ,
 148 .Xr condvar 9 ,
 149 .Xr kthread 9 ,
 150 .Xr softint 9