1.\" $FreeBSD: head/share/man/man3/pthread_testcancel.3 53812 1999-11-28 05:38:13Z alfred $
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
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
64receipt of a cancellation request. The 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
82below) is reached. If 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
117functions will return zero. Otherwise, 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
125asynchronously canceled. For 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
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
131on other objects.
132.Pp
133First, cancelability should only be disabled on entry to an object, never
134explicitly enabled. On 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
140thread is canceled while executing some sequence of actions. If 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
149upon entry to an object. But 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 ---
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
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
64receipt of a cancellation request. The 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
82below) is reached. If 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
117functions will return zero. Otherwise, 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
125asynchronously canceled. For 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
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
131on other objects.
132.Pp
133First, cancelability should only be disabled on entry to an object, never
134explicitly enabled. On 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
140thread is canceled while executing some sequence of actions. If 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
149upon entry to an object. But 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 ---