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