linuxthreads/man/pthread_cancel.man

   1 .TH PTHREAD_CANCEL 3 LinuxThreads
   2
   3 .XREF pthread_setcancelstate
   4 .XREF pthread_setcanceltype
   5 .XREF pthread_testcancel
   6
   7 .SH NAME
   8 pthread_cancel, pthread_setcancelstate, pthread_setcanceltype, pthread_testcancel \- thread cancellation
   9
  10 .SH SYNOPSIS
  11 #include <pthread.h>
  12
  13 int pthread_cancel(pthread_t thread);
  14
  15 int pthread_setcancelstate(int state, int *oldstate);
  16
  17 int pthread_setcanceltype(int type, int *oldtype);
  18
  19 void pthread_testcancel(void);
  20
  21 .SH DESCRIPTION
  22
  23 Cancellation is the mechanism by which a thread can terminate the
  24 execution of another thread. More precisely, a thread can send a
  25 cancellation request to another thread. Depending on its settings, the
  26 target thread can then either ignore the request, honor it
  27 immediately, or defer it till it reaches a cancellation point.
  28
  29 When a thread eventually honors a cancellation request, it performs as
  30 if !pthread_exit(PTHREAD_CANCELED)! has been called at that point:
  31 all cleanup handlers are executed in reverse order, finalization
  32 functions for thread-specific data are called, and finally the thread
  33 stops executing with the return value !PTHREAD_CANCELED!. See
  34 !pthread_exit!(3) for more information.
  35
  36 !pthread_cancel! sends a cancellation request to the thread denoted
  37 by the |thread| argument.
  38
  39 !pthread_setcancelstate! changes the cancellation state for the
  40 calling thread -- that is, whether cancellation requests are ignored
  41 or not. The |state| argument is the new cancellation state: either
  42 !PTHREAD_CANCEL_ENABLE! to enable cancellation, or
  43 !PTHREAD_CANCEL_DISABLE! to disable cancellation (cancellation
  44 requests are ignored). If |oldstate| is not !NULL!, the previous
  45 cancellation state is stored in the location pointed to by |oldstate|,
  46 and can thus be restored later by another call to
  47 !pthread_setcancelstate!.
  48
  49 !pthread_setcanceltype! changes the type of responses to cancellation
  50 requests for the calling thread: asynchronous (immediate) or deferred.
  51 The |type| argument is the new cancellation type: either
  52 !PTHREAD_CANCEL_ASYNCHRONOUS! to cancel the calling thread as soon as
  53 the cancellation request is received, or !PTHREAD_CANCEL_DEFERRED! to
  54 keep the cancellation request pending until the next cancellation
  55 point. If |oldtype| is not !NULL!, the previous
  56 cancellation state is stored in the location pointed to by |oldtype|,
  57 and can thus be restored later by another call to
  58 !pthread_setcanceltype!.
  59
  60 Threads are always created by !pthread_create!(3) with cancellation
  61 enabled and deferred. That is, the initial cancellation state is
  62 !PTHREAD_CANCEL_ENABLE! and the initial type is
  63 !PTHREAD_CANCEL_DEFERRED!.
  64
  65 Cancellation points are those points in the program execution where a
  66 test for pending cancellation requests is performed and cancellation
  67 is executed if positive. The following POSIX threads functions
  68 are cancellation points:
  69
  70 !pthread_join!(3)
  71 .br
  72 !pthread_cond_wait!(3)
  73 .br
  74 !pthread_cond_timedwait!(3)
  75 .br
  76 !pthread_testcancel!(3)
  77 .br
  78 !sem_wait!(3)
  79 .br
  80 !sigwait!(3)
  81
  82 All other POSIX threads functions are guaranteed not to be
  83 cancellation points. That is, they never perform cancellation in
  84 deferred cancellation mode.
  85
  86 !pthread_testcancel! does nothing except testing for pending
  87 cancellation and executing it. Its purpose is to introduce explicit
  88 checks for cancellation in long sequences of code that do not call
  89 cancellation point functions otherwise.
  90
  91 .SH "RETURN VALUE"
  92
  93 !pthread_cancel!, !pthread_setcancelstate! and
  94 !pthread_setcanceltype! return 0 on success and a non-zero error code
  95 on error.
  96
  97 .SH ERRORS
  98 !pthread_cancel! returns the following error code on error:
  99 .RS
 100 .TP
 101 !ESRCH!
 102 no thread could be found corresponding to that specified by the |thread| ID.
 103 .RE
 104
 105 !pthread_setcancelstate! returns the following error code on error:
 106 .RS
 107 .TP
 108 !EINVAL!
 109 the |state| argument is not !PTHREAD_CANCEL_ENABLE! nor
 110 !PTHREAD_CANCEL_DISABLE!
 111 .RE
 112
 113 !pthread_setcanceltype! returns the following error code on error:
 114 .RS
 115 .TP
 116 !EINVAL!
 117 the |type| argument is not !PTHREAD_CANCEL_DEFERRED! nor
 118 !PTHREAD_CANCEL_ASYNCHRONOUS!
 119 .RE
 120
 121 .SH AUTHOR
 122 Xavier Leroy <Xavier.Leroy@inria.fr>
 123
 124 .SH "SEE ALSO"
 125 !pthread_exit!(3),
 126 !pthread_cleanup_push!(3),
 127 !pthread_cleanup_pop!(3).
 128
 129 .SH BUGS
 130
 131 POSIX specifies that a number of system calls (basically, all
 132 system calls that may block, such as !read!(2), !write!(2), !wait!(2),
 133 etc.) and library functions that may call these system calls (e.g.
 134 !fprintf!(3)) are cancellation points.  LinuxThreads is not yet
 135 integrated enough with the C library to implement this, and thus none
 136 of the C library functions is a cancellation point.
 137
 138 For system calls at least, there is a workaround. Cancellation
 139 requests are transmitted to the target thread by sending it a
 140 signal. That signal will interrupt all blocking system calls, causing
 141 them to return immediately with the !EINTR! error. So, checking for
 142 cancellation during a !read! system call, for instance, can be
 143 achieved as follows:
 144
 145 .RS
 146 .ft 3
 147 .nf
 148 .sp
 149 pthread_testcancel();
 150 retcode = read(fd, buffer, length);
 151 pthread_testcancel();
 152 .ft
 153 .LP
 154 .RE
 155 .fi