share/man/man3/pthread_testcancel.3

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