diff options
Diffstat (limited to 'usr/src/man/man5/cancellation.5')
| -rw-r--r-- | usr/src/man/man5/cancellation.5 | 429 |
1 files changed, 0 insertions, 429 deletions
diff --git a/usr/src/man/man5/cancellation.5 b/usr/src/man/man5/cancellation.5 deleted file mode 100644 index 8cd2eb8f62..0000000000 --- a/usr/src/man/man5/cancellation.5 +++ /dev/null @@ -1,429 +0,0 @@ -.\" -.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for -.\" permission to reproduce portions of its copyrighted documentation. -.\" Original documentation from The Open Group can be obtained online at -.\" http://www.opengroup.org/bookstore/. -.\" -.\" The Institute of Electrical and Electronics Engineers and The Open -.\" Group, have given us permission to reprint portions of their -.\" documentation. -.\" -.\" In the following statement, the phrase ``this text'' refers to portions -.\" of the system documentation. -.\" -.\" Portions of this text are reprinted and reproduced in electronic form -.\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition, -.\" Standard for Information Technology -- Portable Operating System -.\" Interface (POSIX), The Open Group Base Specifications Issue 6, -.\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics -.\" Engineers, Inc and The Open Group. In the event of any discrepancy -.\" between these versions and the original IEEE and The Open Group -.\" Standard, the original IEEE and The Open Group Standard is the referee -.\" document. The original Standard can be obtained online at -.\" http://www.opengroup.org/unix/online.html. -.\" -.\" This notice shall appear on any product containing this material. -.\" -.\" 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. -.\" -.\" 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. -.\" -.\" 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] -.\" -.\" -.\" Portions Copyright (c) 1995 IEEE. All Rights Reserved. -.\" Copyright (c) 2001, The IEEE and The Open Group. All Rights Reserved. -.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. -.\" -.TH CANCELLATION 5 "Oct 4, 2005" -.SH NAME -cancellation \- overview of concepts related to POSIX thread cancellation -.SH DESCRIPTION -.TS -box; -c | c -l | l . -FUNCTION ACTION -_ -\fBpthread_cancel()\fR Cancels thread execution. -\fBpthread_setcancelstate()\fR Sets the cancellation \fIstate\fR of a thread. -\fBpthread_setcanceltype()\fR Sets the cancellation \fItype\fR of a thread. -\fBpthread_testcancel()\fR T{ -Creates a cancellation point in the calling thread. -T} -\fBpthread_cleanup_push()\fR Pushes a cleanup handler routine. -\fBpthread_cleanup_pop()\fR Pops a cleanup handler routine. -.TE - -.SS "Cancellation" -.LP -Thread cancellation allows a thread to terminate the execution of any -application thread in the process. Cancellation is useful when further -operations of one or more threads are undesirable or unnecessary. -.sp -.LP -An example of a situation that could benefit from using cancellation is an -asynchronously-generated cancel condition such as a user requesting to close or -exit some running operation. Another example is the completion of a task -undertaken by a number of threads, such as solving a maze. While many threads -search for the solution, one of the threads might solve the puzzle while the -others continue to operate. Since they are serving no purpose at that point, -they should all be canceled. -.SS "Planning Steps" -.LP -Planning and programming for most cancellations follow this pattern: -.RS +4 -.TP -1. -Identify which threads you want to cancel, and insert -\fBpthread_cancel\fR(3C) statements. -.RE -.RS +4 -.TP -2. -Identify system-defined cancellation points where a thread that might be -canceled could have changed system or program state that should be restored. -See the \fBCancellation Points\fR for a list. -.RE -.RS +4 -.TP -3. -When a thread changes the system or program state just before a cancellation -point, and should restore that state before the thread is canceled, place a -cleanup handler before the cancellation point with -\fBpthread_cleanup_push\fR(3C). Wherever a thread restores the changed state, -pop the cleanup handler from the cleanup stack with -\fBpthread_cleanup_pop\fR(3C). -.RE -.RS +4 -.TP -4. -Know whether the threads you are canceling call into cancel-unsafe -libraries, and disable cancellation with \fBpthread_setcancelstate\fR(3C) -before the call into the library. See \fBCancellation State\fR and -\fBCancel-Safe\fR. -.RE -.RS +4 -.TP -5. -To cancel a thread in a procedure that contains no cancellation points, -insert your own cancellation points with \fBpthread_testcancel\fR(3C). This -function creates cancellation points by testing for pending cancellations and -performing those cancellations if they are found. Push and pop cleanup handlers -around the cancellation point, if necessary (see Step 3, above). -.RE -.SS "Cancellation Points" -.LP -The system defines certain points at which cancellation can occur (cancellation -points), and you can create additional cancellation points in your application -with \fBpthread_testcancel()\fR. -.sp -.LP -The following cancellation points are defined by the system (system-defined -cancellation points): \fBcreat\fR(2), \fBaio_suspend\fR(3C), \fBclose\fR(2), -\fBcreat\fR(2), \fBgetmsg\fR(2), \fBgetpmsg\fR(2), \fBlockf\fR(3C), -\fBmq_receive\fR(3C), \fBmq_send\fR(3C), \fBmsgrcv\fR(2), \fBmsgsnd\fR(2), -\fBmsync\fR(3C), \fBnanosleep\fR(3C), \fBopen\fR(2), \fBpause\fR(2), -\fBpoll\fR(2), \fBpread\fR(2), \fBpthread_cond_timedwait\fR(3C), -\fBpthread_cond_wait\fR(3C), \fBpthread_join\fR(3C), -\fBpthread_testcancel\fR(3C), \fBputmsg\fR(2), \fBputpmsg\fR(2), -\fBpwrite\fR(2), \fBread\fR(2), \fBreadv\fR(2), \fBselect\fR(3C), -\fBsem_wait\fR(3C), \fBsigpause\fR(3C), \fBsigwaitinfo\fR(3C), -\fBsigsuspend\fR(2), \fBsigtimedwait\fR(3C), \fBsigwait\fR(2), \fBsleep\fR(3C), -\fBsync\fR(2), \fBsystem\fR(3C), \fBtcdrain\fR(3C), \fBusleep\fR(3C), -\fBwait\fR(3C), \fBwaitid\fR(2), \fBwait3\fR(3C), \fBwaitpid\fR(3C), -\fBwrite\fR(2), \fBwritev\fR(2), and \fBfcntl\fR(2), when specifying -\fBF_SETLKW\fR as the command. -.sp -.LP -When cancellation is asynchronous, cancellation can occur at any time (before, -during, or after the execution of the function defined as the cancellation -point). When cancellation is deferred (the default case), cancellation occurs -only within the scope of a function defined as a cancellation point (after the -function is called and before the function returns). See \fBCancellation -Type\fR for more information about deferred and asynchronous cancellation. -.sp -.LP -Choosing where to place cancellation points and understanding how cancellation -affects your program depend upon your understanding of both your application -and of cancellation mechanics. -.sp -.LP -Typically, any call that might require a long wait should be a cancellation -point. Operations need to check for pending cancellation requests when the -operation is about to block indefinitely. This includes threads waiting in -\fBpthread_cond_wait()\fR and \fBpthread_cond_timedwait()\fR, threads waiting -for the termination of another thread in \fBpthread_join()\fR, and threads -blocked on \fBsigwait()\fR. -.sp -.LP -A mutex is explicitly not a cancellation point and should be held for only the -minimal essential time. -.sp -.LP -Most of the dangers in performing cancellations deal with properly restoring -invariants and freeing shared resources. For example, a carelessly canceled -thread might leave a mutex in a locked state, leading to a deadlock. Or it -might leave a region of memory allocated with no way to identify it and -therefore no way to free it. -.SS "Cleanup Handlers" -.LP -When a thread is canceled, it should release resources and clean up the state -that is shared with other threads. So, whenever a thread that might be canceled -changes the state of the system or of the program, be sure to push a cleanup -handler with \fBpthread_cleanup_push\fR(3C) before the cancellation point. -.sp -.LP -When a thread is canceled, all the currently-stacked cleanup handlers are -executed in last-in-first-out (LIFO) order. Each handler is run in the scope in -which it was pushed. When the last cleanup handler returns, the thread-specific -data destructor functions are called. Thread execution terminates when the last -destructor function returns. -.sp -.LP -When, in the normal course of the program, an uncanceled thread restores state -that it had previously changed, be sure to pop the cleanup handler (that you -had set up where the change took place) using \fBpthread_cleanup_pop\fR(3C). -That way, if the thread is canceled later, only currently-changed state will be -restored by the handlers that are left in the stack. -.sp -.LP -The \fBpthread_cleanup_push()\fR and \fBpthread_cleanup_pop()\fR functions can -be implemented as macros. The application must ensure that they appear as -statements, and in pairs within the same lexical scope (that is, the -\fBpthread_cleanup_push()\fR macro can be thought to expand to a token list -whose first token is '{' with \fBpthread_cleanup_pop()\fR expanding to a token -list whose last token is the corresponding '}'). -.sp -.LP -The effect of the use of \fBreturn\fR, \fBbreak\fR, \fBcontinue\fR, and -\fBgoto\fR to prematurely leave a code block described by a pair of -\fBpthread_cleanup_push()\fR and \fBpthread_cleanup_pop()\fR function calls is -undefined. -.SS "Cancellation State" -.LP -Most programmers will use only the default cancellation state of -\fBPTHREAD_CANCEL_ENABLE\fR, but can choose to change the state by using -\fBpthread_setcancelstate\fR(3C), which determines whether a thread is -cancelable at all. With the default \fIstate\fR of -\fBPTHREAD_CANCEL_ENABLE\fR, cancellation is enabled and the thread is -cancelable at points determined by its cancellation \fItype\fR. See -\fBCancellation Type\fR. -.sp -.LP -If the \fIstate\fR is \fBPTHREAD_CANCEL_DISABLE\fR, cancellation is disabled, -the thread is not cancelable at any point, and all cancellation requests to it -are held pending. -.sp -.LP -You might want to disable cancellation before a call to a cancel-unsafe -library, restoring the old cancel state when the call returns from the library. -See \fBCancel-Safe\fR for explanations of cancel safety. -.SS "Cancellation Type" -.LP -A thread's cancellation \fBtype\fR is set with \fBpthread_setcanceltype\fR(3C), -and determines whether the thread can be canceled anywhere in its execution or -only at cancellation points. -.sp -.LP -With the default \fItype\fR of \fBPTHREAD_CANCEL_DEFERRED\fR, the thread is -cancelable only at cancellation points, and then only when cancellation is -enabled. -.sp -.LP -If the \fItype\fR is \fBPTHREAD_CANCEL_ASYNCHRONOUS\fR, the thread is -cancelable at any point in its execution (assuming, of course, that -cancellation is enabled). Try to limit regions of asynchronous cancellation to -sequences with no external dependencies that could result in dangling resources -or unresolved state conditions. Using asynchronous cancellation is discouraged -because of the danger involved in trying to guarantee correct cleanup handling -at absolutely every point in the program. -.sp - -.sp -.TS -box; -c | c | c -l | l | l . -Cancellation Type/State Table -Type State - Enabled (Default) Disabled -_ -Deferred (Default) T{ -Cancellation occurs when the target thread reaches a cancellation point and a cancel is pending. (Default) -T} T{ -All cancellation requests to the target thread are held pending. -T} -Asynchronous T{ -Receipt of a \fBpthread_cancel()\fR call causes immediate cancellation. -T} T{ -All cancellation requests to the target thread are held pending; as -soon as cancellation is re-enabled, pending cancellations are executed -immediately. -T} -.TE - -.SS "Cancel-Safe" -.LP -With the arrival of POSIX cancellation, the Cancel-Safe level has been added to -the list of MT-Safety levels. See \fBattributes\fR(5). An application or -library is Cancel-Safe whenever it has arranged for cleanup handlers to restore -system or program state wherever cancellation can occur. The application or -library is specifically Deferred-Cancel-Safe when it is Cancel-Safe for threads -whose cancellation type is \fBPTHREAD_CANCEL_DEFERRED\fR. See \fBCancellation -State\fR. It is specifically Asynchronous-Cancel-Safe when it is Cancel-Safe -for threads whose cancellation type is \fBPTHREAD_CANCEL_ASYNCHRONOUS\fR. -.sp -.LP -It is easier to arrange for deferred cancel safety, as this requires system and -program state protection only around cancellation points. In general, expect -that most applications and libraries are not Asynchronous-Cancel-Safe. -.SS "POSIX Threads Only" -.LP -The cancellation functions described in this manual page are available for -POSIX threads, only (the Solaris threads interfaces do not provide cancellation -functions). -.SH EXAMPLES -.LP -\fBExample 1 \fRCancellation example -.sp -.LP -The following short C++ example shows the pushing/popping of cancellation -handlers, the disabling/enabling of cancellation, the use of -\fBpthread_testcancel()\fR, and so on. The \fBfree_res()\fR cancellation -handler in this example is a dummy function that simply prints a message, but -that would free resources in a real application. The function \fBf2()\fR is -called from the main thread, and goes deep into its call stack by calling -itself recursively. - -.sp -.LP -Before \fBf2()\fR starts running, the newly created thread has probably posted -a cancellation on the main thread since the main thread calls \fBthr_yield()\fR -right after creating thread2. Because cancellation was initially disabled in -the main thread, through a call to \fBpthread_setcancelstate()\fR, the call to -\fBf2()\fR from \fBmain()\fR continues and constructs X at each recursive -call, even though the main thread has a pending cancellation. - -.sp -.LP -When \fBf2()\fR is called for the fifty-first time (when \fB"i == 50"\fR), -\fBf2()\fR enables cancellation by calling \fBpthread_setcancelstate()\fR. It -then establishes a cancellation point for itself by calling -\fBpthread_testcancel()\fR. (Because a cancellation is pending, a call to a -cancellation point such as \fBread\fR(2) or \fBwrite\fR(2) would also cancel -the caller here.) - -.sp -.LP -After the \fBmain()\fR thread is canceled at the fifty-first iteration, all the -cleanup handlers that were pushed are called in sequence; this is indicated by -the calls to \fBfree_res()\fR and the calls to the destructor for \fIX\fR. At -each level, the C++ runtime calls the destructor for \fIX\fR and then the -cancellation handler, \fBfree_res()\fR. The print messages from -\fBfree_res()\fR and \fIX\fR's destructor show the sequence of calls. - -.sp -.LP -At the end, the main thread is joined by thread2. Because the main thread was -canceled, its return status from \fBpthread_join()\fR is -\fBPTHREAD_CANCELED\fR. After the status is printed, thread2 returns, killing -the process (since it is the last thread in the process). - -.sp -.in +2 -.nf -#include <pthread.h> -#include <sched.h> -extern "C" void thr_yield(void); - -extern "C" void printf(...); - -struct X { - int x; - X(int i){x = i; printf("X(%d) constructed.\en", i);} - ~X(){ printf("X(%d) destroyed.\en", x);} -}; - -void -free_res(void *i) -{ - printf("Freeing `%d`\en",i); -} - -char* f2(int i) -{ - try { - X dummy(i); - pthread_cleanup_push(free_res, (void *)i); - if (i == 50) { - pthread_setcancelstate(PTHREAD_CANCEL_ENABLE, NULL); - pthread_testcancel(); - } - f2(i+1); - pthread_cleanup_pop(0); - } - catch (int) { - printf("Error: In handler.\en"); - } - return "f2"; -} - -void * -thread2(void *tid) -{ - void *sts; - - printf("I am new thread :%d\en", pthread_self()); - - pthread_cancel((pthread_t)tid); - - pthread_join((pthread_t)tid, &sts); - - printf("main thread cancelled due to %d\en", sts); - - return (sts); -} - -main() -{ - pthread_setcancelstate(PTHREAD_CANCEL_DISABLE, NULL); - pthread_create(NULL, NULL, thread2, (void *)pthread_self()); - thr_yield(); - printf("Returned from %s\en",f2(0)); -} -.fi -.in -2 - -.SH ATTRIBUTES -.LP -See \fBattributes\fR(5) for descriptions of the following attributes: -.sp - -.sp -.TS -box; -c | c -l | l . -ATTRIBUTE TYPE ATTRIBUTE VALUE -_ -MT-Level MT-Safe -.TE - -.SH SEE ALSO -.LP -\fBread\fR(2), \fBsigwait\fR(2), \fBwrite\fR(2), \fBIntro\fR(3), -\fBcondition\fR(5), \fBpthread_cleanup_pop\fR(3C), -\fBpthread_cleanup_push\fR(3C), \fBpthread_exit\fR(3C), \fBpthread_join\fR(3C), -\fBpthread_setcancelstate\fR(3C), \fBpthread_setcanceltype\fR(3C), -\fBpthread_testcancel\fR(3C), \fBsetjmp\fR(3C), \fBattributes\fR(5), -\fBstandards\fR(5) |