GNU Info

(libc.info)Cancellation

---

Next: Cleanup Handlers Prev: Thread Attributes Up: POSIX Threads

---

Enter node , (file) or (file)node

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.