Print this page
9842 man page typos and spelling
*** 46,58 ****
.\"
.TH CANCELLATION 5 "Oct 4, 2005"
.SH NAME
cancellation \- overview of concepts related to POSIX thread cancellation
.SH DESCRIPTION
- .sp
-
- .sp
.TS
box;
c | c
l | l .
FUNCTION ACTION
--- 46,55 ----
*** 66,76 ****
\fBpthread_cleanup_push()\fR Pushes a cleanup handler routine.
\fBpthread_cleanup_pop()\fR Pops a cleanup handler routine.
.TE
.SS "Cancellation"
- .sp
.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
--- 63,72 ----
*** 81,91 ****
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"
- .sp
.LP
Planning and programming for most cancellations follow this pattern:
.RS +4
.TP
1.
--- 77,86 ----
*** 125,135 ****
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"
- .sp
.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
--- 120,129 ----
*** 180,190 ****
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"
- .sp
.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.
--- 174,183 ----
*** 215,225 ****
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"
- .sp
.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
--- 208,217 ----
*** 235,245 ****
.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"
- .sp
.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
--- 227,236 ----
*** 273,288 ****
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 executedimmediately.
T}
.TE
.SS "Cancel-Safe"
- .sp
.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
--- 264,280 ----
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
*** 294,304 ****
.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"
- .sp
.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
--- 286,295 ----
*** 412,422 ****
}
.fi
.in -2
.SH ATTRIBUTES
- .sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp
.sp
--- 403,412 ----
*** 428,438 ****
_
MT-Level MT-Safe
.TE
.SH SEE ALSO
- .sp
.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),
--- 418,427 ----