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