pthreads/pthread_setcancelstate.3

   1 .\" $FreeBSD: src/lib/libc_r/man/pthread_testcancel.3,v 1.2.2.3 2001/08/17 15:42:52 ru Exp $
   2 .Dd January 17, 1999
   3 .Dt PTHREAD_TESTCANCEL 3
   4 .Os
   5 .Sh NAME
   6 .Nm pthread_setcancelstate ,
   7 .Nm pthread_setcanceltype ,
   8 .Nm pthread_testcancel
   9 .Nd set cancelability state
  10 .Sh SYNOPSIS
  11 .Fd #include <pthread.h>
  12 .Ft int
  13 .Fn pthread_setcancelstate "int state" "int *oldstate"
  14 .Ft int
  15 .Fn pthread_setcanceltype "int type" "int *oldtype"
  16 .Ft void
  17 .Fn pthread_testcancel "void"
  18 .Sh DESCRIPTION
  19 The
  20 .Fn pthread_setcancelstate
  21 function atomically both sets the calling thread's cancelability state
  22 to the indicated
  23 .Fa state
  24 and returns the previous cancelability state at the location referenced by
  25 .Fa oldstate .
  26 Legal values for
  27 .Fa state
  28 are
  29 .Dv PTHREAD_CANCEL_ENABLE
  30 and
  31 .Dv PTHREAD_CANCEL_DISABLE .
  32 .Pp
  33 The
  34 .Fn pthread_setcanceltype
  35 function atomically both sets the calling thread's cancelability type
  36 to the indicated
  37 .Fa type
  38 and returns the previous cancelability type at the location referenced by
  39 .Fa oldtype .
  40 Legal values for
  41 .Fa type
  42 are
  43 .Dv PTHREAD_CANCEL_DEFERRED
  44 and
  45 .Dv PTHREAD_CANCEL_ASYNCHRONOUS .
  46 .Pp
  47 The cancelability state and type of any newly created threads, including the
  48 thread in which
  49 .Fn main
  50 was first invoked, are
  51 .Dv PTHREAD_CANCEL_ENABLE
  52 and
  53 .Dv PTHREAD_CANCEL_DEFERRED
  54 respectively.
  55 .Pp
  56 The
  57 .Fn pthread_testcancel
  58 function creates a cancellation point in the calling thread.
  59 The
  60 .Fn pthread_testcancel
  61 function has no effect if cancelability is disabled.
  62 .Pp
  63 .Ss Cancelability States
  64 The cancelability state of a thread determines the action taken upon
  65 receipt of a cancellation request.
  66 The thread may control cancellation in
  67 a number of ways.
  68 .Pp
  69 Each thread maintains its own
  70 .Dq cancelability state
  71 which may be encoded in two bits:
  72 .Bl -hang
  73 .It Em Cancelability Enable
  74 When cancelability is
  75 .Dv PTHREAD_CANCEL_DISABLE ,
  76 cancellation requests against the target thread are held pending.
  77 .It Em Cancelability Type
  78 When cancelability is enabled and the cancelability type is
  79 .Dv PTHREAD_CANCEL_ASYNCHRONOUS ,
  80 new or pending cancellation requests may be acted upon at any time.
  81 When cancelability is enabled and the cancelability type is
  82 .Dv PTHREAD_CANCEL_DEFERRED ,
  83 cancellation requests are held pending until a cancellation point (see
  84 below) is reached.
  85 If cancelability is disabled, the setting of the
  86 cancelability type has no immediate effect as all cancellation requests
  87 are held pending; however, once cancelability is enabled again the new
  88 type will be in effect.
  89 .El
  90 .Ss Cancellation Points
  91 Cancellation points will occur when a thread is executing the following
  92 functions:
  93 .Fn close ,
  94 .Fn creat ,
  95 .Fn fcntl ,
  96 .Fn fsync ,
  97 .Fn msync ,
  98 .Fn nanosleep ,
  99 .Fn open ,
 100 .Fn pause ,
 101 .Fn pthread_cond_timedwait ,
 102 .Fn pthread_cond_wait ,
 103 .Fn pthread_join ,
 104 .Fn pthread_testcancel ,
 105 .Fn read ,
 106 .Fn sigwaitinfo ,
 107 .Fn sigsuspend ,
 108 .Fn sigwait ,
 109 .Fn sleep ,
 110 .Fn system ,
 111 .Fn tcdrain ,
 112 .Fn wait ,
 113 .Fn waitpid ,
 114 .Fn write .
 115 .Sh RETURN VALUES
 116 If successful, the
 117 .Fn pthread_setcancelstate
 118 and
 119 .Fn pthread_setcanceltype
 120 functions will return zero.
 121 Otherwise, an error number shall be returned to
 122 indicate the error.
 123 .Pp
 124 The
 125 .Fn pthread_setcancelstate
 126 and
 127 .Fn pthread_setcanceltype
 128 functions are used to control the points at which a thread may be
 129 asynchronously canceled.
 130 For cancellation control to be usable in modular
 131 fashion, some rules must be followed.
 132 .Pp
 133 For purposes of this discussion, consider an object to be a generalization
 134 of a procedure.
 135 It is a set of procedures and global variables written as
 136 a unit and called by clients not known by the object.
 137 Objects may depend
 138 on other objects.
 139 .Pp
 140 First, cancelability should only be disabled on entry to an object, never
 141 explicitly enabled.
 142 On exit from an object, the cancelability state should
 143 always be restored to its value on entry to the object.
 144 .Pp
 145 This follows from a modularity argument: if the client of an object (or the
 146 client of an object that uses that object) has disabled cancelability, it is
 147 because the client doesn't want to have to worry about how to clean up if the
 148 thread is canceled while executing some sequence of actions.
 149 If an object
 150 is called in such a state and it enables cancelability and a cancellation
 151 request is pending for that thread, then the thread will be canceled,
 152 contrary to the wish of the client that disabled.
 153 .Pp
 154 Second, the cancelability type may be explicitly set to either
 155 .Em deferred
 156 or
 157 .Em asynchronous
 158 upon entry to an object.
 159 But as with the cancelability state, on exit from
 160 an object that cancelability type should always be restored to its value on
 161 entry to the object.
 162 .Pp
 163 Finally, only functions that are cancel-safe may be called from a thread that
 164 is asynchronously cancelable.
 165 .Sh ERRORS
 166 The function
 167 .Fn pthread_setcancelstate
 168 may fail with:
 169 .Bl -tag -width Er
 170 .It Bq Er EINVAL
 171 The specified state is not
 172 .Dv PTHREAD_CANCEL_ENABLE
 173 or
 174 .Dv PTHREAD_CANCEL_DISABLE .
 175 .El
 176 .Pp
 177 The function
 178 .Fn pthread_setcanceltype
 179 may fail with:
 180 .Bl -tag -width Er
 181 .It Bq Er EINVAL
 182 The specified state is not
 183 .Dv PTHREAD_CANCEL_DEFERRED
 184 or
 185 .Dv PTHREAD_CANCEL_ASYNCHRONOUS .
 186 .El
 187 .Sh SEE ALSO
 188 .Xr pthread_cancel 3
 189 .Sh STANDARDS
 190 .Fn pthread_testcancel
 191 conforms to
 192 .St -p1003.1-96 .
 193 .Sh AUTHORS
 194 This man page was written by
 195 .An David Leonard Aq d@openbsd.org
 196 for the
 197 .Ox
 198 implementation of
 199 .Xr pthread_cancel 3 .