pthread_cancel

PTHREAD_CANCEL(3)           Library Functions Manual           PTHREAD_CANCEL(3)



NAME
       pthread_cancel, pthread_setcancelstate, pthread_setcanceltype,
       pthread_testcancel - thread cancellation


SYNOPSIS
       #include <pthread.h>

       int pthread_cancel(pthread_t thread);

       int pthread_setcancelstate(int state, int *oldstate);

       int pthread_setcanceltype(int type, int *oldtype);

       void pthread_testcancel(void);


DESCRIPTION
       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 a thread eventually honors a cancellation request, it performs as if
       pthread_exit(PTHREAD_CANCELED) has been called at that point: all cleanup
       handlers are executed in reverse order, finalization functions for
       thread-specific data are called, and finally the thread stops executing
       with the return value PTHREAD_CANCELED.  See pthread_exit(3) for more
       information.

       pthread_cancel sends a cancellation request to the thread denoted by the
       thread argument.

       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.

       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.

       Threads are always created by pthread_create(3) with cancellation enabled
       and deferred. That is, the initial cancellation state is
       PTHREAD_CANCEL_ENABLE and the initial type is PTHREAD_CANCEL_DEFERRED.

       Cancellation points are those points in the program execution where a
       test for pending cancellation requests is performed and cancellation is
       executed if positive. The following POSIX threads functions are
       cancellation points:

       pthread_join(3)
       pthread_cond_wait(3)
       pthread_cond_timedwait(3)
       pthread_testcancel(3)
       sem_wait(3)
       sigwait(3)

       All other POSIX threads functions are guaranteed not to be cancellation
       points. That is, they never perform cancellation in deferred cancellation
       mode.

       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.


RETURN VALUE
       pthread_cancel, pthread_setcancelstate and pthread_setcanceltype return 0
       on success and a non-zero error code on error.


ERRORS
       pthread_cancel returns the following error code on error:

              ESRCH  no thread could be found corresponding to that specified by
                     the thread ID.

       pthread_setcancelstate returns the following error code on error:

              EINVAL the state argument is not PTHREAD_CANCEL_ENABLE nor
                     PTHREAD_CANCEL_DISABLE

       pthread_setcanceltype returns the following error code on error:

              EINVAL the type argument is not PTHREAD_CANCEL_DEFERRED nor
                     PTHREAD_CANCEL_ASYNCHRONOUS


AUTHOR
       Xavier Leroy <Xavier.Leroy@inria.fr>


SEE ALSO
       pthread_exit(3), pthread_cleanup_push(3), pthread_cleanup_pop(3).


BUGS
       POSIX specifies that a number of system calls (basically, all system
       calls that may block, such as read(2), write(2), wait(2), etc.) and
       library functions that may call these system calls (e.g.  fprintf(3)) are
       cancellation points.  LinuxThreads is not yet integrated enough with the
       C library to implement this, and thus none of the C library functions is
       a cancellation point.

       For system calls at least, there is a workaround. Cancellation requests
       are transmitted to the target thread by sending it a signal. That signal
       will interrupt all blocking system calls, causing them to return
       immediately with the EINTR error. So, checking for cancellation during a
       read system call, for instance, can be achieved as follows:


              pthread_testcancel();
              retcode = read(fd, buffer, length);
              pthread_testcancel();

                                  LinuxThreads                 PTHREAD_CANCEL(3)