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