Ubuntu manuals

Provided by: glibc-doc_2.7-10ubuntu3_all

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)