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 "Mar 1, 2005" 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 .sp 54 .LP 55 Solaris DDI specific (Solaris DDI) 56 .SH PARAMETERS 57 .sp 58 .ne 2 59 .na 60 \fB\fIdip\fR\fR 61 .ad 62 .RS 12n 63 Pointer to the device's dev_info structure. May be NULL for kernel 64 modules that do not have an associated dev_info structure. 65 .RE 66 67 .sp 68 .ne 2 69 .na 70 \fB\fIname\fR\fR 71 .ad 72 .RS 12n 73 Descriptive string. Only alphanumeric characters can be used in name 74 and spaces are not allowed. The name should be unique. 75 .RE 76 77 .sp 78 .ne 2 79 .na 80 \fB\fInthreads\fR\fR 81 .ad 82 .RS 12n 83 Number of threads servicing the task queue. Note that the request ordering is 84 guaranteed (tasks are processed in the order scheduled) if the \fBtaskq\fR is 85 created with a single servicing thread. 86 .RE 87 88 .sp 89 .ne 2 90 .na 91 \fB\fIpri\fR\fR 92 .ad 93 .RS 12n 94 Priority of threads servicing the task queue. Drivers and modules should 95 specify TASKQ_DEFAULTPRI. 96 .RE 97 98 .sp 99 .ne 2 100 .na 101 \fB\fIcflags\fR\fR 102 .ad 103 .RS 12n 104 Should pass 0 as flags. 105 .RE 106 107 .sp 108 .ne 2 109 .na 110 \fB\fIfunc\fR\fR 111 .ad 112 .RS 12n 113 Callback function to call. 114 .RE 115 116 .sp 117 .ne 2 118 .na 119 \fB\fIarg\fR\fR 120 .ad 121 .RS 12n 122 Argument to the callback function. 123 .RE 124 125 .sp 126 .ne 2 127 .na 128 \fB\fIdflags\fR\fR 129 .ad 130 .RS 12n 131 Possible \fIdflags\fR are: 132 .sp 133 .ne 2 134 .na 135 \fBDDI_SLEEP\fR 136 .ad 137 .RS 15n 138 Allow sleeping (blocking) until memory is available. 139 .RE 140 141 .sp 142 .ne 2 143 .na 144 \fBDDI_NOSLEEP\fR 145 .ad 146 .RS 15n 147 Return DDI_FAILURE immediately if memory is not available. 148 .RE 149 150 .RE 151 152 .sp 153 .ne 2 154 .na 155 \fB\fItq\fR\fR 156 .ad 157 .RS 12n 158 Pointer to a task queue (ddi_taskq_t *). 159 .RE 160 161 .sp 162 .ne 2 163 .na 164 \fB\fItp\fR\fR 165 .ad 166 .RS 12n 167 Pointer to a thread structure. 168 .RE 169 170 .SH DESCRIPTION 171 .sp 172 .LP 173 A kernel task queue is a mechanism for general-purpose asynchronous task 174 scheduling that enables tasks to be performed at a later time by another 175 thread. There are several reasons why you may utilize asynchronous task 176 scheduling: 177 .RS +4 178 .TP 179 1. 180 You have a task that isn't time-critical, but a current code path that is. 181 .RE 182 .RS +4 183 .TP 184 2. 185 You have a task that may require grabbing locks that a thread already holds. 186 .RE 187 .RS +4 188 .TP 189 3. 190 You have a task that needs to block (for example, to wait for memory), but a 191 have a thread that cannot block in its current context. 192 .RE 193 .RS +4 194 .TP 195 4. 196 You have a code path that can't complete because of a specific condition, 197 but also can't sleep or fail. In this case, the task is immediately queued and 198 then is executed after the condition disappears. 199 .RE 200 .RS +4 201 .TP 202 5. 203 A task queue is just a simple way to launch multiple tasks in parallel. 204 .RE 205 .sp 206 .LP 207 A task queue consists of a list of tasks, together with one or more threads to 208 service the list. If a task queue has a single service thread, all tasks are 209 guaranteed to execute in the order they were dispatched. Otherwise they can be 210 executed in any order. Note that since tasks are placed on a list, execution of 211 one task and should not depend on the execution of another task or a deadlock 212 may occur. A \fBtaskq\fR created with a single servicing thread guarantees that 213 all the tasks are serviced in the order in which they are scheduled. 214 .sp 215 .LP 216 The \fBddi_taskq_create()\fR function creates a task queue instance. 217 .sp 218 .LP 219 The \fBddi_taskq_dispatch()\fR function places \fBtaskq\fR on the list for 220 later execution. The \fIdflag\fR argument specifies whether it is allowed sleep 221 waiting for memory. DDI_SLEEP dispatches can sleep and are guaranteed to 222 succeed. DDI_NOSLEEP dispatches are guaranteed not to sleep but may fail 223 (return \fBDDI_FAILURE\fR) if resources are not available. 224 .sp 225 .LP 226 The \fBddi_taskq_destroy()\fR function waits for any scheduled tasks to 227 complete, then destroys the \fBtaskq\fR. The caller should guarantee that no 228 new tasks are scheduled for the closing \fBtaskq\fR. 229 .sp 230 .LP 231 The \fBddi_taskq_wait()\fR function waits for all previously scheduled tasks to 232 complete. Note that this function does not stop any new task dispatches. 233 .sp 234 .LP 235 The \fBddi_taskq_suspend()\fR function suspends all task execution until 236 \fBddi_taskq_resume()\fR is called. Although \fBddi_taskq_suspend()\fR attempts 237 to suspend pending tasks, there are no guarantees that they will be suspended. 238 The only guarantee is that all tasks dispatched after \fBddi_taskq_suspend()\fR 239 will not be executed. Because it will trigger a deadlock, the 240 \fBddi_taskq_suspend()\fR function should never be called by a task executing 241 on a \fBtaskq\fR. 242 .sp 243 .LP 244 The \fBddi_taskq_suspended()\fR function returns \fBB_TRUE\fR if \fBtaskq\fR is 245 suspended, and \fBB_FALSE\fR otherwise. It is intended to ASSERT that the task 246 queue is suspended. 247 .sp 248 .LP 249 The \fBddi_taskq_resume()\fR function resumes task queue execution. 250 .SH RETURN VALUES 251 .sp 252 .LP 253 The \fBddi_taskq_create()\fR function creates an opaque handle that is used for 254 all other \fBtaskq\fR operations. It returns a \fBtaskq\fR pointer on success 255 and NULL on failure. 256 .sp 257 .LP 258 The \fBddi_taskq_dispatch()\fR function returns \fBDDI_FAILURE\fR if it can't 259 dispatch a task and returns \fBDDI_SUCCESS\fR if dispatch succeeded. 260 .sp 261 .LP 262 The \fBddi_taskq_suspended()\fR function returns \fBB_TRUE\fR if \fBtaskq\fR is 263 suspended. Otherwise \fBB_FALSE\fR is returned. 264 .SH CONTEXT 265 .sp 266 .LP 267 All functions may be called from the user or kernel contexts. 268 .sp 269 .LP 270 Addtionally, the \fBddi_taskq_dispatch\fR function may be called from the 271 interrupt context only if the DDI_NOSLEEP flag is set.