Cancellation
============
Cancellation is the mechanism by which a thread can terminate the
execution of another thread. More precisely, a thread can send a
cancellation request to another thread. Depending on its settings, the
target thread can then either ignore the request, honor it immediately,
or defer it till it reaches a cancellation point. When threads are
first created by `pthread_create', they always defer cancellation
requests.
When a thread eventually honors a cancellation request, it behaves
as if `pthread_exit(PTHREAD_CANCELED)' was called. All cleanup handlers
are executed in reverse order, finalization functions for
thread-specific data are called, and finally the thread stops executing.
If the canceled thread was joinable, the return value
`PTHREAD_CANCELED' is provided to whichever thread calls PTHREAD_JOIN
on it. See `pthread_exit' for more information.
Cancellation points are the points where the thread checks for
pending cancellation requests and performs them. The POSIX threads
functions `pthread_join', `pthread_cond_wait',
`pthread_cond_timedwait', `pthread_testcancel', `sem_wait', and
`sigwait' are cancellation points. In addition, these system calls are
cancellation points:
accept open sendmsg
close pause sendto
connect read system
fcntl recv tcdrain
fsync recvfrom wait
lseek recvmsg waitpid
msync send write
nanosleep
All library functions that call these functions (such as `printf') are
also cancellation points.
- Function: int pthread_setcancelstate (int STATE, int *OLDSTATE)
`pthread_setcancelstate' changes the cancellation state for the
calling thread - that is, whether cancellation requests are
ignored or not. The STATE argument is the new cancellation state:
either `PTHREAD_CANCEL_ENABLE' to enable cancellation, or
`PTHREAD_CANCEL_DISABLE' to disable cancellation (cancellation
requests are ignored).
If OLDSTATE is not `NULL', the previous cancellation state is
stored in the location pointed to by OLDSTATE, and can thus be
restored later by another call to `pthread_setcancelstate'.
If the STATE argument is not `PTHREAD_CANCEL_ENABLE' or
`PTHREAD_CANCEL_DISABLE', `pthread_setcancelstate' fails and
returns `EINVAL'. Otherwise it returns 0.
- Function: int pthread_setcanceltype (int TYPE, int *OLDTYPE)
`pthread_setcanceltype' changes the type of responses to
cancellation requests for the calling thread: asynchronous
(immediate) or deferred. The TYPE argument is the new
cancellation type: either `PTHREAD_CANCEL_ASYNCHRONOUS' to cancel
the calling thread as soon as the cancellation request is
received, or `PTHREAD_CANCEL_DEFERRED' to keep the cancellation
request pending until the next cancellation point. If OLDTYPE is
not `NULL', the previous cancellation state is stored in the
location pointed to by OLDTYPE, and can thus be restored later by
another call to `pthread_setcanceltype'.
If the TYPE argument is not `PTHREAD_CANCEL_DEFERRED' or
`PTHREAD_CANCEL_ASYNCHRONOUS', `pthread_setcanceltype' fails and
returns `EINVAL'. Otherwise it returns 0.
- Function: void pthread_testcancel (VOID)
`pthread_testcancel' does nothing except testing for pending
cancellation and executing it. Its purpose is to introduce explicit
checks for cancellation in long sequences of code that do not call
cancellation point functions otherwise.