pthread_testcancel

PTHREAD_CANCEL(3)                                            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  exe-
       cution of another thread. More precisely, a thread can send a cancella-
       tion 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 exe-
       cuting 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_CAN-
       CEL_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_CAN-
       CEL_ASYNCHRONOUS to cancel the calling thread as soon as the  cancella-
       tion  request  is received, or PTHREAD_CANCEL_DEFERRED to keep the can-
       cellation 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 cancel-
       lation 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  cancella-
       tion mode.

       pthread_testcancel does nothing except testing for pending cancellation
       and executing it. Its purpose is to introduce explicit checks for  can-
       cellation 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  sig-
       nal  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)