usr/src/man/man9f/taskq.9f

   1 '\" te
   2 .\" Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved.
   3 .\" Copyright 1989 AT&T
   4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   5 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   6 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   7 .TH TASKQ 9F "Jul 25, 2015"
   8 .SH NAME
   9 taskq, ddi_taskq_create, ddi_taskq_destroy, ddi_taskq_dispatch, ddi_taskq_wait,
  10 ddi_taskq_suspend, taskq_suspended, ddi_taskq_resume \- Kernel task queue
  11 operations
  12 .SH SYNOPSIS
  13 .LP
  14 .nf
  15 #include <sys/sunddi.h>
  16
  17 \fBddi_taskq_t *\fR\fBddi_taskq_create\fR(\fBdev_info_t *\fR\fIdip\fR, \fBconst char *\fR\fIname\fR,
  18      \fBint\fR \fInthreads\fR, \fBpri_t\fR  \fIpri\fR, \fBuint_t\fR  \fIcflags\fR);
  19 .fi
  20
  21 .LP
  22 .nf
  23 \fBvoid\fR \fBddi_taskq_destroy\fR(\fBddi_taskq_t *\fR\fItq\fR);
  24 .fi
  25
  26 .LP
  27 .nf
  28 \fBint\fR \fBddi_taskq_dispatch\fR(\fBddi_taskq_t *\fR\fItq\fR, \fBvoid (*\fR \fIfunc)\fR(void *),
  29      \fBvoid *\fR\fIarg\fR, \fBuint_t\fR \fIdflags\fR);
  30 .fi
  31
  32 .LP
  33 .nf
  34 \fBvoid\fR \fBddi_taskq_wait\fR(\fBddi_taskq_t *\fR\fItq\fR);
  35 .fi
  36
  37 .LP
  38 .nf
  39 \fBvoid\fR \fBddi_taskq_suspend\fR(\fBddi_taskq_t *\fR\fItq\fR);
  40 .fi
  41
  42 .LP
  43 .nf
  44 \fBboolean_t\fR \fBddi_taskq_suspended\fR(\fBddi_taskq_t *\fR\fItq\fR);
  45 .fi
  46
  47 .LP
  48 .nf
  49 \fBvoid\fR \fBddi_taskq_resume\fR(\fBddi_taskq_t *\fR\fItq\fR);
  50 .fi
  51
  52 .SH INTERFACE LEVEL
  53 .LP
  54 Solaris DDI specific (Solaris DDI)
  55 .SH PARAMETERS
  56 .ne 2
  57 .na
  58 \fB\fIdip\fR\fR
  59 .ad
  60 .RS 12n
  61 Pointer to the device's dev_info structure. May be NULL for kernel
  62 modules that do not have an associated dev_info structure.
  63 .RE
  64
  65 .sp
  66 .ne 2
  67 .na
  68 \fB\fIname\fR\fR
  69 .ad
  70 .RS 12n
  71 Descriptive string. Only alphanumeric characters can be used            in name
  72 and spaces are not allowed. The name should be unique.
  73 .RE
  74
  75 .sp
  76 .ne 2
  77 .na
  78 \fB\fInthreads\fR\fR
  79 .ad
  80 .RS 12n
  81 Number of threads servicing the task queue. Note that the request ordering is
  82 guaranteed (tasks are processed in the order scheduled) if the \fBtaskq\fR is
  83 created with a single servicing thread.
  84 .RE
  85
  86 .sp
  87 .ne 2
  88 .na
  89 \fB\fIpri\fR\fR
  90 .ad
  91 .RS 12n
  92 Priority of threads servicing the task queue. Drivers and modules should
  93 specify TASKQ_DEFAULTPRI.
  94 .RE
  95
  96 .sp
  97 .ne 2
  98 .na
  99 \fB\fIcflags\fR\fR
 100 .ad
 101 .RS 12n
 102 Should pass 0 as flags.
 103 .RE
 104
 105 .sp
 106 .ne 2
 107 .na
 108 \fB\fIfunc\fR\fR
 109 .ad
 110 .RS 12n
 111 Callback function to call.
 112 .RE
 113
 114 .sp
 115 .ne 2
 116 .na
 117 \fB\fIarg\fR\fR
 118 .ad
 119 .RS 12n
 120 Argument to the callback function.
 121 .RE
 122
 123 .sp
 124 .ne 2
 125 .na
 126 \fB\fIdflags\fR\fR
 127 .ad
 128 .RS 12n
 129 Possible \fIdflags\fR are:
 130 .sp
 131 .ne 2
 132 .na
 133 \fBDDI_SLEEP\fR
 134 .ad
 135 .RS 15n
 136 Allow sleeping (blocking) until memory is available.
 137 .RE
 138
 139 .sp
 140 .ne 2
 141 .na
 142 \fBDDI_NOSLEEP\fR
 143 .ad
 144 .RS 15n
 145 Return DDI_FAILURE immediately if memory is not  available.
 146 .RE
 147
 148 .RE
 149
 150 .sp
 151 .ne 2
 152 .na
 153 \fB\fItq\fR\fR
 154 .ad
 155 .RS 12n
 156 Pointer to a task queue (ddi_taskq_t *).
 157 .RE
 158
 159 .sp
 160 .ne 2
 161 .na
 162 \fB\fItp\fR\fR
 163 .ad
 164 .RS 12n
 165 Pointer to a thread structure.
 166 .RE
 167
 168 .SH DESCRIPTION
 169 .LP
 170 A kernel task queue is a mechanism for general-purpose asynchronous task
 171 scheduling that enables tasks to be performed at a later time by another
 172 thread. There are several reasons why you may utilize asynchronous task
 173 scheduling:
 174 .RS +4
 175 .TP
 176 1.
 177 You have a task that isn't time-critical, but a current code path that is.
 178 .RE
 179 .RS +4
 180 .TP
 181 2.
 182 You have a task that may require grabbing locks that a thread already holds.
 183 .RE
 184 .RS +4
 185 .TP
 186 3.
 187 You have a task that needs to block (for example, to wait for memory), but you
 188 have a thread that cannot block in its current context.
 189 .RE
 190 .RS +4
 191 .TP
 192 4.
 193 You have a code path that can't complete because of a specific condition,
 194 but also can't sleep or fail. In this case, the task is immediately queued and
 195 then is executed after the condition disappears.
 196 .RE
 197 .RS +4
 198 .TP
 199 5.
 200 A task queue is just a simple way to launch multiple tasks in parallel.
 201 .RE
 202 .sp
 203 .LP
 204 A task queue consists of a list of tasks, together with one or more threads to
 205 service the list. If a task queue has a single service thread, all tasks are
 206 guaranteed to execute in the order they were dispatched. Otherwise they can be
 207 executed in any order. Note that since tasks are placed on a list, execution of
 208 one task should not depend on the execution of another task or a deadlock
 209 may occur.
 210 .sp
 211 .LP
 212 The \fBddi_taskq_create()\fR function creates a task queue instance.
 213 .sp
 214 .LP
 215 The \fBddi_taskq_dispatch()\fR function places \fBtaskq\fR on the list for
 216 later execution. The \fIdflag\fR argument specifies whether it is allowed sleep
 217 waiting  for memory. DDI_SLEEP dispatches can sleep and are guaranteed to
 218 succeed. DDI_NOSLEEP dispatches are guaranteed not to sleep but may fail
 219 (return \fBDDI_FAILURE\fR) if resources are not available.
 220 .sp
 221 .LP
 222 The \fBddi_taskq_destroy()\fR function waits for any scheduled tasks to
 223 complete, then destroys the \fBtaskq\fR. The caller should guarantee that no
 224 new tasks are scheduled for the closing \fBtaskq\fR.
 225 .sp
 226 .LP
 227 The \fBddi_taskq_wait()\fR function waits for all previously scheduled tasks to
 228 complete. Note that this function does not stop any new task dispatches.
 229 .sp
 230 .LP
 231 The \fBddi_taskq_suspend()\fR function suspends all task execution until
 232 \fBddi_taskq_resume()\fR is called. Although \fBddi_taskq_suspend()\fR attempts
 233 to suspend pending tasks, there are no guarantees that they will be suspended.
 234 The only guarantee is that all tasks dispatched after \fBddi_taskq_suspend()\fR
 235 will not be executed. Because it will trigger a deadlock, the
 236 \fBddi_taskq_suspend()\fR function should never be called by a task executing
 237 on a \fBtaskq\fR.
 238 .sp
 239 .LP
 240 The \fBddi_taskq_suspended()\fR function returns \fBB_TRUE\fR if \fBtaskq\fR is
 241 suspended, and \fBB_FALSE\fR otherwise. It is intended to ASSERT that the task
 242 queue is suspended.
 243 .sp
 244 .LP
 245 The \fBddi_taskq_resume()\fR function resumes task queue execution.
 246 .SH RETURN VALUES
 247 .LP
 248 The \fBddi_taskq_create()\fR function creates an opaque handle that is used for
 249 all other \fBtaskq\fR operations. It returns a \fBtaskq\fR pointer on success
 250 and NULL on failure.
 251 .sp
 252 .LP
 253 The \fBddi_taskq_dispatch()\fR function returns \fBDDI_FAILURE\fR if it can't
 254 dispatch a task and returns \fBDDI_SUCCESS\fR if dispatch succeeded.
 255 .sp
 256 .LP
 257 The \fBddi_taskq_suspended()\fR function returns \fBB_TRUE\fR if \fBtaskq\fR is
 258 suspended. Otherwise \fBB_FALSE\fR is returned.
 259 .SH CONTEXT
 260 .LP
 261 All functions may be called from the user or kernel contexts.
 262 .sp
 263 .LP
 264 Addtionally, the \fBddi_taskq_dispatch\fR function may be called from the
 265 interrupt context only if the DDI_NOSLEEP flag is set.