| pthread_testcancel.3 (53812) | pthread_testcancel.3 (57686) |
|---|---|
| 1.\" $FreeBSD: head/share/man/man3/pthread_testcancel.3 53812 1999-11-28 05:38:13Z alfred $ | 1.\" $FreeBSD: head/share/man/man3/pthread_testcancel.3 57686 2000-03-02 09:14:21Z sheldonh $ |
| 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 --- 40 unchanged lines hidden (view full) --- 50was first invoked, are 51.Dv PTHREAD_CANCEL_ENABLE 52and 53.Dv PTHREAD_CANCEL_DEFERRED 54respectively. 55.Pp 56The 57.Fn pthread_testcancel | 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 --- 40 unchanged lines hidden (view full) --- 50was first invoked, are 51.Dv PTHREAD_CANCEL_ENABLE 52and 53.Dv PTHREAD_CANCEL_DEFERRED 54respectively. 55.Pp 56The 57.Fn pthread_testcancel |
| 58function creates a cancellation point in the calling thread. The | 58function creates a cancellation point in the calling thread. 59The |
| 59.Fn pthread_testcancel 60function has no effect if cancelability is disabled. 61.Pp 62.Ss Cancelability States 63The cancelability state of a thread determines the action taken upon | 60.Fn pthread_testcancel 61function has no effect if cancelability is disabled. 62.Pp 63.Ss Cancelability States 64The cancelability state of a thread determines the action taken upon |
| 64receipt of a cancellation request. The thread may control cancellation in | 65receipt of a cancellation request. 66The thread may control cancellation in |
| 65a number of ways. 66.Pp 67Each thread maintains its own 68.Dq cancelability state 69which may be encoded in two bits: 70.Bl -hang 71.It Em Cancelability Enable 72When cancelability is 73.Dv PTHREAD_CANCEL_DISABLE , 74cancellation requests against the target thread are held pending. 75.It Em Cancelability Type 76When cancelability is enabled and the cancelability type is 77.Dv PTHREAD_CANCEL_ASYNCHRONOUS , 78new or pending cancellation requests may be acted upon at any time. 79When cancelability is enabled and the cancelability type is 80.Dv PTHREAD_CANCEL_DEFERRED , 81cancellation requests are held pending until a cancellation point (see | 67a number of ways. 68.Pp 69Each thread maintains its own 70.Dq cancelability state 71which may be encoded in two bits: 72.Bl -hang 73.It Em Cancelability Enable 74When cancelability is 75.Dv PTHREAD_CANCEL_DISABLE , 76cancellation requests against the target thread are held pending. 77.It Em Cancelability Type 78When cancelability is enabled and the cancelability type is 79.Dv PTHREAD_CANCEL_ASYNCHRONOUS , 80new or pending cancellation requests may be acted upon at any time. 81When cancelability is enabled and the cancelability type is 82.Dv PTHREAD_CANCEL_DEFERRED , 83cancellation requests are held pending until a cancellation point (see |
| 82below) is reached. If cancelability is disabled, the setting of the | 84below) is reached. 85If cancelability is disabled, the setting of the |
| 83cancelability type has no immediate effect as all cancellation requests 84are held pending; however, once cancelability is enabled again the new 85type will be in effect. 86.El 87.Ss Cancellation Points 88Cancellation points will occur when a thread is executing the following 89functions: 90.Fn close , --- 18 unchanged lines hidden (view full) --- 109.Fn wait , 110.Fn waitpid , 111.Fn write . 112.Sh RETURN VALUES 113If successful, the 114.Fn pthread_setcancelstate 115and 116.Fn pthread_setcanceltype | 86cancelability type has no immediate effect as all cancellation requests 87are held pending; however, once cancelability is enabled again the new 88type will be in effect. 89.El 90.Ss Cancellation Points 91Cancellation points will occur when a thread is executing the following 92functions: 93.Fn close , --- 18 unchanged lines hidden (view full) --- 112.Fn wait , 113.Fn waitpid , 114.Fn write . 115.Sh RETURN VALUES 116If successful, the 117.Fn pthread_setcancelstate 118and 119.Fn pthread_setcanceltype |
| 117functions will return zero. Otherwise, an error number shall be returned to | 120functions will return zero. 121Otherwise, an error number shall be returned to |
| 118indicate the error. 119.Pp 120The 121.Fn pthread_setcancelstate 122and 123.Fn pthread_setcanceltype 124functions are used to control the points at which a thread may be | 122indicate the error. 123.Pp 124The 125.Fn pthread_setcancelstate 126and 127.Fn pthread_setcanceltype 128functions are used to control the points at which a thread may be |
| 125asynchronously canceled. For cancellation control to be usable in modular | 129asynchronously canceled. 130For cancellation control to be usable in modular |
| 126fashion, some rules must be followed. 127.Pp 128For purposes of this discussion, consider an object to be a generalization | 131fashion, some rules must be followed. 132.Pp 133For purposes of this discussion, consider an object to be a generalization |
| 129of a procedure. It is a set of procedures and global variables written as 130a unit and called by clients not known by the object. Objects may depend | 134of a procedure. 135It is a set of procedures and global variables written as 136a unit and called by clients not known by the object. 137Objects may depend |
| 131on other objects. 132.Pp 133First, cancelability should only be disabled on entry to an object, never | 138on other objects. 139.Pp 140First, cancelability should only be disabled on entry to an object, never |
| 134explicitly enabled. On exit from an object, the cancelability state should | 141explicitly enabled. 142On exit from an object, the cancelability state should |
| 135always be restored to its value on entry to the object. 136.Pp 137This follows from a modularity argument: if the client of an object (or the 138client of an object that uses that object) has disabled cancelability, it is 139because the client doesn't want to have to worry about how to clean up if the | 143always be restored to its value on entry to the object. 144.Pp 145This follows from a modularity argument: if the client of an object (or the 146client of an object that uses that object) has disabled cancelability, it is 147because the client doesn't want to have to worry about how to clean up if the |
| 140thread is canceled while executing some sequence of actions. If an object | 148thread is canceled while executing some sequence of actions. 149If an object |
| 141is called in such a state and it enables cancelability and a cancellation 142request is pending for that thread, then the thread will be canceled, 143contrary to the wish of the client that disabled. 144.Pp 145Second, the cancelability type may be explicitly set to either 146.Em deferred 147or 148.Em asynchronous | 150is called in such a state and it enables cancelability and a cancellation 151request is pending for that thread, then the thread will be canceled, 152contrary to the wish of the client that disabled. 153.Pp 154Second, the cancelability type may be explicitly set to either 155.Em deferred 156or 157.Em asynchronous |
| 149upon entry to an object. But as with the cancelability state, on exit from | 158upon entry to an object. 159But as with the cancelability state, on exit from |
| 150an object that cancelability type should always be restored to its value on 151entry to the object. 152.Pp 153Finally, only functions that are cancel-safe may be called from a thread that 154is asynchronously cancelable. 155.Sh ERRORS 156The function 157.Fn pthread_setcancelstate --- 30 unchanged lines hidden --- | 160an object that cancelability type should always be restored to its value on 161entry to the object. 162.Pp 163Finally, only functions that are cancel-safe may be called from a thread that 164is asynchronously cancelable. 165.Sh ERRORS 166The function 167.Fn pthread_setcancelstate --- 30 unchanged lines hidden --- |