lib/libpthread/pthread_testcancel.3

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