Print this page
9842 man page typos and spelling
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man5/cancellation.5
+++ new/usr/src/man/man5/cancellation.5
1 1 .\"
2 2 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
3 3 .\" permission to reproduce portions of its copyrighted documentation.
4 4 .\" Original documentation from The Open Group can be obtained online at
5 5 .\" http://www.opengroup.org/bookstore/.
6 6 .\"
7 7 .\" The Institute of Electrical and Electronics Engineers and The Open
8 8 .\" Group, have given us permission to reprint portions of their
9 9 .\" documentation.
10 10 .\"
11 11 .\" In the following statement, the phrase ``this text'' refers to portions
12 12 .\" of the system documentation.
13 13 .\"
14 14 .\" Portions of this text are reprinted and reproduced in electronic form
15 15 .\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
16 16 .\" Standard for Information Technology -- Portable Operating System
17 17 .\" Interface (POSIX), The Open Group Base Specifications Issue 6,
18 18 .\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
19 19 .\" Engineers, Inc and The Open Group. In the event of any discrepancy
20 20 .\" between these versions and the original IEEE and The Open Group
21 21 .\" Standard, the original IEEE and The Open Group Standard is the referee
22 22 .\" document. The original Standard can be obtained online at
23 23 .\" http://www.opengroup.org/unix/online.html.
24 24 .\"
25 25 .\" This notice shall appear on any product containing this material.
26 26 .\"
27 27 .\" The contents of this file are subject to the terms of the
28 28 .\" Common Development and Distribution License (the "License").
29 29 .\" You may not use this file except in compliance with the License.
30 30 .\"
31 31 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
32 32 .\" or http://www.opensolaris.org/os/licensing.
33 33 .\" See the License for the specific language governing permissions
34 34 .\" and limitations under the License.
35 35 .\"
36 36 .\" When distributing Covered Code, include this CDDL HEADER in each
37 37 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
38 38 .\" If applicable, add the following below this CDDL HEADER, with the
39 39 .\" fields enclosed by brackets "[]" replaced with your own identifying
40 40 .\" information: Portions Copyright [yyyy] [name of copyright owner]
|
↓ open down ↓ |
40 lines elided |
↑ open up ↑ |
41 41 .\"
42 42 .\"
43 43 .\" Portions Copyright (c) 1995 IEEE. All Rights Reserved.
44 44 .\" Copyright (c) 2001, The IEEE and The Open Group. All Rights Reserved.
45 45 .\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved.
46 46 .\"
47 47 .TH CANCELLATION 5 "Oct 4, 2005"
48 48 .SH NAME
49 49 cancellation \- overview of concepts related to POSIX thread cancellation
50 50 .SH DESCRIPTION
51 -.sp
52 -
53 -.sp
54 51 .TS
55 52 box;
56 53 c | c
57 54 l | l .
58 55 FUNCTION ACTION
59 56 _
60 57 \fBpthread_cancel()\fR Cancels thread execution.
61 58 \fBpthread_setcancelstate()\fR Sets the cancellation \fIstate\fR of a thread.
62 59 \fBpthread_setcanceltype()\fR Sets the cancellation \fItype\fR of a thread.
63 60 \fBpthread_testcancel()\fR T{
64 61 Creates a cancellation point in the calling thread.
65 62 T}
66 63 \fBpthread_cleanup_push()\fR Pushes a cleanup handler routine.
67 64 \fBpthread_cleanup_pop()\fR Pops a cleanup handler routine.
68 65 .TE
69 66
70 67 .SS "Cancellation"
71 -.sp
72 68 .LP
73 69 Thread cancellation allows a thread to terminate the execution of any
74 70 application thread in the process. Cancellation is useful when further
75 71 operations of one or more threads are undesirable or unnecessary.
76 72 .sp
77 73 .LP
78 74 An example of a situation that could benefit from using cancellation is an
79 75 asynchronously-generated cancel condition such as a user requesting to close or
80 76 exit some running operation. Another example is the completion of a task
81 77 undertaken by a number of threads, such as solving a maze. While many threads
82 78 search for the solution, one of the threads might solve the puzzle while the
83 79 others continue to operate. Since they are serving no purpose at that point,
84 80 they should all be canceled.
85 81 .SS "Planning Steps"
86 -.sp
87 82 .LP
88 83 Planning and programming for most cancellations follow this pattern:
89 84 .RS +4
90 85 .TP
91 86 1.
92 87 Identify which threads you want to cancel, and insert
93 88 \fBpthread_cancel\fR(3C) statements.
94 89 .RE
95 90 .RS +4
96 91 .TP
97 92 2.
98 93 Identify system-defined cancellation points where a thread that might be
99 94 canceled could have changed system or program state that should be restored.
100 95 See the \fBCancellation Points\fR for a list.
101 96 .RE
102 97 .RS +4
103 98 .TP
104 99 3.
105 100 When a thread changes the system or program state just before a cancellation
106 101 point, and should restore that state before the thread is canceled, place a
107 102 cleanup handler before the cancellation point with
108 103 \fBpthread_cleanup_push\fR(3C). Wherever a thread restores the changed state,
109 104 pop the cleanup handler from the cleanup stack with
110 105 \fBpthread_cleanup_pop\fR(3C).
111 106 .RE
112 107 .RS +4
113 108 .TP
114 109 4.
115 110 Know whether the threads you are canceling call into cancel-unsafe
116 111 libraries, and disable cancellation with \fBpthread_setcancelstate\fR(3C)
117 112 before the call into the library. See \fBCancellation State\fR and
118 113 \fBCancel-Safe\fR.
119 114 .RE
|
↓ open down ↓ |
23 lines elided |
↑ open up ↑ |
120 115 .RS +4
121 116 .TP
122 117 5.
123 118 To cancel a thread in a procedure that contains no cancellation points,
124 119 insert your own cancellation points with \fBpthread_testcancel\fR(3C). This
125 120 function creates cancellation points by testing for pending cancellations and
126 121 performing those cancellations if they are found. Push and pop cleanup handlers
127 122 around the cancellation point, if necessary (see Step 3, above).
128 123 .RE
129 124 .SS "Cancellation Points"
130 -.sp
131 125 .LP
132 126 The system defines certain points at which cancellation can occur (cancellation
133 127 points), and you can create additional cancellation points in your application
134 128 with \fBpthread_testcancel()\fR.
135 129 .sp
136 130 .LP
137 131 The following cancellation points are defined by the system (system-defined
138 132 cancellation points): \fBcreat\fR(2), \fBaio_suspend\fR(3C), \fBclose\fR(2),
139 133 \fBcreat\fR(2), \fBgetmsg\fR(2), \fBgetpmsg\fR(2), \fBlockf\fR(3C),
140 134 \fBmq_receive\fR(3C), \fBmq_send\fR(3C), \fBmsgrcv\fR(2), \fBmsgsnd\fR(2),
141 135 \fBmsync\fR(3C), \fBnanosleep\fR(3C), \fBopen\fR(2), \fBpause\fR(2),
142 136 \fBpoll\fR(2), \fBpread\fR(2), \fBpthread_cond_timedwait\fR(3C),
143 137 \fBpthread_cond_wait\fR(3C), \fBpthread_join\fR(3C),
144 138 \fBpthread_testcancel\fR(3C), \fBputmsg\fR(2), \fBputpmsg\fR(2),
145 139 \fBpwrite\fR(2), \fBread\fR(2), \fBreadv\fR(2), \fBselect\fR(3C),
146 140 \fBsem_wait\fR(3C), \fBsigpause\fR(3C), \fBsigwaitinfo\fR(3C),
147 141 \fBsigsuspend\fR(2), \fBsigtimedwait\fR(3C), \fBsigwait\fR(2), \fBsleep\fR(3C),
148 142 \fBsync\fR(2), \fBsystem\fR(3C), \fBtcdrain\fR(3C), \fBusleep\fR(3C),
149 143 \fBwait\fR(3C), \fBwaitid\fR(2), \fBwait3\fR(3C), \fBwaitpid\fR(3C),
150 144 \fBwrite\fR(2), \fBwritev\fR(2), and \fBfcntl\fR(2), when specifying
151 145 \fBF_SETLKW\fR as the command.
152 146 .sp
153 147 .LP
154 148 When cancellation is asynchronous, cancellation can occur at any time (before,
155 149 during, or after the execution of the function defined as the cancellation
156 150 point). When cancellation is deferred (the default case), cancellation occurs
157 151 only within the scope of a function defined as a cancellation point (after the
158 152 function is called and before the function returns). See \fBCancellation
159 153 Type\fR for more information about deferred and asynchronous cancellation.
160 154 .sp
161 155 .LP
162 156 Choosing where to place cancellation points and understanding how cancellation
163 157 affects your program depend upon your understanding of both your application
164 158 and of cancellation mechanics.
165 159 .sp
166 160 .LP
167 161 Typically, any call that might require a long wait should be a cancellation
168 162 point. Operations need to check for pending cancellation requests when the
169 163 operation is about to block indefinitely. This includes threads waiting in
170 164 \fBpthread_cond_wait()\fR and \fBpthread_cond_timedwait()\fR, threads waiting
171 165 for the termination of another thread in \fBpthread_join()\fR, and threads
172 166 blocked on \fBsigwait()\fR.
173 167 .sp
174 168 .LP
|
↓ open down ↓ |
34 lines elided |
↑ open up ↑ |
175 169 A mutex is explicitly not a cancellation point and should be held for only the
176 170 minimal essential time.
177 171 .sp
178 172 .LP
179 173 Most of the dangers in performing cancellations deal with properly restoring
180 174 invariants and freeing shared resources. For example, a carelessly canceled
181 175 thread might leave a mutex in a locked state, leading to a deadlock. Or it
182 176 might leave a region of memory allocated with no way to identify it and
183 177 therefore no way to free it.
184 178 .SS "Cleanup Handlers"
185 -.sp
186 179 .LP
187 180 When a thread is canceled, it should release resources and clean up the state
188 181 that is shared with other threads. So, whenever a thread that might be canceled
189 182 changes the state of the system or of the program, be sure to push a cleanup
190 183 handler with \fBpthread_cleanup_push\fR(3C) before the cancellation point.
191 184 .sp
192 185 .LP
193 186 When a thread is canceled, all the currently-stacked cleanup handlers are
194 187 executed in last-in-first-out (LIFO) order. Each handler is run in the scope in
195 188 which it was pushed. When the last cleanup handler returns, the thread-specific
196 189 data destructor functions are called. Thread execution terminates when the last
197 190 destructor function returns.
198 191 .sp
199 192 .LP
200 193 When, in the normal course of the program, an uncanceled thread restores state
201 194 that it had previously changed, be sure to pop the cleanup handler (that you
202 195 had set up where the change took place) using \fBpthread_cleanup_pop\fR(3C).
203 196 That way, if the thread is canceled later, only currently-changed state will be
204 197 restored by the handlers that are left in the stack.
205 198 .sp
206 199 .LP
207 200 The \fBpthread_cleanup_push()\fR and \fBpthread_cleanup_pop()\fR functions can
208 201 be implemented as macros. The application must ensure that they appear as
209 202 statements, and in pairs within the same lexical scope (that is, the
|
↓ open down ↓ |
14 lines elided |
↑ open up ↑ |
210 203 \fBpthread_cleanup_push()\fR macro can be thought to expand to a token list
211 204 whose first token is '{' with \fBpthread_cleanup_pop()\fR expanding to a token
212 205 list whose last token is the corresponding '}').
213 206 .sp
214 207 .LP
215 208 The effect of the use of \fBreturn\fR, \fBbreak\fR, \fBcontinue\fR, and
216 209 \fBgoto\fR to prematurely leave a code block described by a pair of
217 210 \fBpthread_cleanup_push()\fR and \fBpthread_cleanup_pop()\fR function calls is
218 211 undefined.
219 212 .SS "Cancellation State"
220 -.sp
221 213 .LP
222 214 Most programmers will use only the default cancellation state of
223 215 \fBPTHREAD_CANCEL_ENABLE\fR, but can choose to change the state by using
224 216 \fBpthread_setcancelstate\fR(3C), which determines whether a thread is
225 217 cancelable at all. With the default \fIstate\fR of
226 218 \fBPTHREAD_CANCEL_ENABLE\fR, cancellation is enabled and the thread is
227 219 cancelable at points determined by its cancellation \fItype\fR. See
228 220 \fBCancellation Type\fR.
229 221 .sp
230 222 .LP
231 223 If the \fIstate\fR is \fBPTHREAD_CANCEL_DISABLE\fR, cancellation is disabled,
232 224 the thread is not cancelable at any point, and all cancellation requests to it
233 225 are held pending.
234 226 .sp
235 227 .LP
236 228 You might want to disable cancellation before a call to a cancel-unsafe
237 229 library, restoring the old cancel state when the call returns from the library.
238 230 See \fBCancel-Safe\fR for explanations of cancel safety.
239 231 .SS "Cancellation Type"
240 -.sp
241 232 .LP
242 233 A thread's cancellation \fBtype\fR is set with \fBpthread_setcanceltype\fR(3C),
243 234 and determines whether the thread can be canceled anywhere in its execution or
244 235 only at cancellation points.
245 236 .sp
246 237 .LP
247 238 With the default \fItype\fR of \fBPTHREAD_CANCEL_DEFERRED\fR, the thread is
248 239 cancelable only at cancellation points, and then only when cancellation is
249 240 enabled.
250 241 .sp
251 242 .LP
252 243 If the \fItype\fR is \fBPTHREAD_CANCEL_ASYNCHRONOUS\fR, the thread is
253 244 cancelable at any point in its execution (assuming, of course, that
254 245 cancellation is enabled). Try to limit regions of asynchronous cancellation to
255 246 sequences with no external dependencies that could result in dangling resources
256 247 or unresolved state conditions. Using asynchronous cancellation is discouraged
257 248 because of the danger involved in trying to guarantee correct cleanup handling
258 249 at absolutely every point in the program.
259 250 .sp
260 251
261 252 .sp
262 253 .TS
263 254 box;
264 255 c | c | c
265 256 l | l | l .
266 257 Cancellation Type/State Table
267 258 Type State
|
↓ open down ↓ |
17 lines elided |
↑ open up ↑ |
268 259 Enabled (Default) Disabled
269 260 _
270 261 Deferred (Default) T{
271 262 Cancellation occurs when the target thread reaches a cancellation point and a cancel is pending. (Default)
272 263 T} T{
273 264 All cancellation requests to the target thread are held pending.
274 265 T}
275 266 Asynchronous T{
276 267 Receipt of a \fBpthread_cancel()\fR call causes immediate cancellation.
277 268 T} T{
278 -All cancellation requests to the target thread are held pending; as soon as cancellation is re-enabled, pending cancellations are executedimmediately.
269 +All cancellation requests to the target thread are held pending; as
270 +soon as cancellation is re-enabled, pending cancellations are executed
271 +immediately.
279 272 T}
280 273 .TE
281 274
282 275 .SS "Cancel-Safe"
283 -.sp
284 276 .LP
285 277 With the arrival of POSIX cancellation, the Cancel-Safe level has been added to
286 278 the list of MT-Safety levels. See \fBattributes\fR(5). An application or
287 279 library is Cancel-Safe whenever it has arranged for cleanup handlers to restore
288 280 system or program state wherever cancellation can occur. The application or
289 281 library is specifically Deferred-Cancel-Safe when it is Cancel-Safe for threads
290 282 whose cancellation type is \fBPTHREAD_CANCEL_DEFERRED\fR. See \fBCancellation
291 283 State\fR. It is specifically Asynchronous-Cancel-Safe when it is Cancel-Safe
292 284 for threads whose cancellation type is \fBPTHREAD_CANCEL_ASYNCHRONOUS\fR.
293 285 .sp
294 286 .LP
295 287 It is easier to arrange for deferred cancel safety, as this requires system and
296 288 program state protection only around cancellation points. In general, expect
297 289 that most applications and libraries are not Asynchronous-Cancel-Safe.
298 290 .SS "POSIX Threads Only"
299 -.sp
300 291 .LP
301 292 The cancellation functions described in this manual page are available for
302 293 POSIX threads, only (the Solaris threads interfaces do not provide cancellation
303 294 functions).
304 295 .SH EXAMPLES
305 296 .LP
306 297 \fBExample 1 \fRCancellation example
307 298 .sp
308 299 .LP
309 300 The following short C++ example shows the pushing/popping of cancellation
310 301 handlers, the disabling/enabling of cancellation, the use of
311 302 \fBpthread_testcancel()\fR, and so on. The \fBfree_res()\fR cancellation
312 303 handler in this example is a dummy function that simply prints a message, but
313 304 that would free resources in a real application. The function \fBf2()\fR is
314 305 called from the main thread, and goes deep into its call stack by calling
315 306 itself recursively.
316 307
317 308 .sp
318 309 .LP
319 310 Before \fBf2()\fR starts running, the newly created thread has probably posted
320 311 a cancellation on the main thread since the main thread calls \fBthr_yield()\fR
321 312 right after creating thread2. Because cancellation was initially disabled in
322 313 the main thread, through a call to \fBpthread_setcancelstate()\fR, the call to
323 314 \fBf2()\fR from \fBmain()\fR continues and constructs X at each recursive
324 315 call, even though the main thread has a pending cancellation.
325 316
326 317 .sp
327 318 .LP
328 319 When \fBf2()\fR is called for the fifty-first time (when \fB"i == 50"\fR),
329 320 \fBf2()\fR enables cancellation by calling \fBpthread_setcancelstate()\fR. It
330 321 then establishes a cancellation point for itself by calling
331 322 \fBpthread_testcancel()\fR. (Because a cancellation is pending, a call to a
332 323 cancellation point such as \fBread\fR(2) or \fBwrite\fR(2) would also cancel
333 324 the caller here.)
334 325
335 326 .sp
336 327 .LP
337 328 After the \fBmain()\fR thread is canceled at the fifty-first iteration, all the
338 329 cleanup handlers that were pushed are called in sequence; this is indicated by
339 330 the calls to \fBfree_res()\fR and the calls to the destructor for \fIX\fR. At
340 331 each level, the C++ runtime calls the destructor for \fIX\fR and then the
341 332 cancellation handler, \fBfree_res()\fR. The print messages from
342 333 \fBfree_res()\fR and \fIX\fR's destructor show the sequence of calls.
343 334
344 335 .sp
345 336 .LP
346 337 At the end, the main thread is joined by thread2. Because the main thread was
347 338 canceled, its return status from \fBpthread_join()\fR is
348 339 \fBPTHREAD_CANCELED\fR. After the status is printed, thread2 returns, killing
349 340 the process (since it is the last thread in the process).
350 341
351 342 .sp
352 343 .in +2
353 344 .nf
354 345 #include <pthread.h>
355 346 #include <sched.h>
356 347 extern "C" void thr_yield(void);
357 348
358 349 extern "C" void printf(...);
359 350
360 351 struct X {
361 352 int x;
362 353 X(int i){x = i; printf("X(%d) constructed.\en", i);}
363 354 ~X(){ printf("X(%d) destroyed.\en", x);}
364 355 };
365 356
366 357 void
367 358 free_res(void *i)
368 359 {
369 360 printf("Freeing `%d`\en",i);
370 361 }
371 362
372 363 char* f2(int i)
373 364 {
374 365 try {
375 366 X dummy(i);
376 367 pthread_cleanup_push(free_res, (void *)i);
377 368 if (i == 50) {
378 369 pthread_setcancelstate(PTHREAD_CANCEL_ENABLE, NULL);
379 370 pthread_testcancel();
380 371 }
381 372 f2(i+1);
382 373 pthread_cleanup_pop(0);
383 374 }
384 375 catch (int) {
385 376 printf("Error: In handler.\en");
386 377 }
387 378 return "f2";
388 379 }
389 380
390 381 void *
391 382 thread2(void *tid)
392 383 {
393 384 void *sts;
394 385
395 386 printf("I am new thread :%d\en", pthread_self());
396 387
397 388 pthread_cancel((pthread_t)tid);
398 389
399 390 pthread_join((pthread_t)tid, &sts);
400 391
401 392 printf("main thread cancelled due to %d\en", sts);
402 393
403 394 return (sts);
404 395 }
405 396
406 397 main()
|
↓ open down ↓ |
97 lines elided |
↑ open up ↑ |
407 398 {
408 399 pthread_setcancelstate(PTHREAD_CANCEL_DISABLE, NULL);
409 400 pthread_create(NULL, NULL, thread2, (void *)pthread_self());
410 401 thr_yield();
411 402 printf("Returned from %s\en",f2(0));
412 403 }
413 404 .fi
414 405 .in -2
415 406
416 407 .SH ATTRIBUTES
417 -.sp
418 408 .LP
419 409 See \fBattributes\fR(5) for descriptions of the following attributes:
420 410 .sp
421 411
422 412 .sp
423 413 .TS
424 414 box;
425 415 c | c
426 416 l | l .
427 417 ATTRIBUTE TYPE ATTRIBUTE VALUE
428 418 _
429 419 MT-Level MT-Safe
430 420 .TE
431 421
432 422 .SH SEE ALSO
433 -.sp
434 423 .LP
435 424 \fBread\fR(2), \fBsigwait\fR(2), \fBwrite\fR(2), \fBIntro\fR(3),
436 425 \fBcondition\fR(5), \fBpthread_cleanup_pop\fR(3C),
437 426 \fBpthread_cleanup_push\fR(3C), \fBpthread_exit\fR(3C), \fBpthread_join\fR(3C),
438 427 \fBpthread_setcancelstate\fR(3C), \fBpthread_setcanceltype\fR(3C),
439 428 \fBpthread_testcancel\fR(3C), \fBsetjmp\fR(3C), \fBattributes\fR(5),
440 429 \fBstandards\fR(5)
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX