1 |
1325 |
phoenix |
@node POSIX Threads
|
2 |
|
|
@c @node POSIX Threads, , Top, Top
|
3 |
|
|
@chapter POSIX Threads
|
4 |
|
|
@c %MENU% The standard threads library
|
5 |
|
|
|
6 |
|
|
@c This chapter needs more work bigtime. -zw
|
7 |
|
|
|
8 |
|
|
This chapter describes the pthreads (POSIX threads) library. This
|
9 |
|
|
library provides support functions for multithreaded programs: thread
|
10 |
|
|
primitives, synchronization objects, and so forth. It also implements
|
11 |
|
|
POSIX 1003.1b semaphores (not to be confused with System V semaphores).
|
12 |
|
|
|
13 |
|
|
The threads operations (@samp{pthread_*}) do not use @var{errno}.
|
14 |
|
|
Instead they return an error code directly. The semaphore operations do
|
15 |
|
|
use @var{errno}.
|
16 |
|
|
|
17 |
|
|
@menu
|
18 |
|
|
* Basic Thread Operations:: Creating, terminating, and waiting for threads.
|
19 |
|
|
* Thread Attributes:: Tuning thread scheduling.
|
20 |
|
|
* Cancellation:: Stopping a thread before it's done.
|
21 |
|
|
* Cleanup Handlers:: Deallocating resources when a thread is
|
22 |
|
|
cancelled.
|
23 |
|
|
* Mutexes:: One way to synchronize threads.
|
24 |
|
|
* Condition Variables:: Another way.
|
25 |
|
|
* POSIX Semaphores:: And a third way.
|
26 |
|
|
* Thread-Specific Data:: Variables with different values in
|
27 |
|
|
different threads.
|
28 |
|
|
* Threads and Signal Handling:: Why you should avoid mixing the two, and
|
29 |
|
|
how to do it if you must.
|
30 |
|
|
* Miscellaneous Thread Functions:: A grab bag of utility routines.
|
31 |
|
|
@end menu
|
32 |
|
|
|
33 |
|
|
@node Basic Thread Operations
|
34 |
|
|
@section Basic Thread Operations
|
35 |
|
|
|
36 |
|
|
These functions are the thread equivalents of @code{fork}, @code{exit},
|
37 |
|
|
and @code{wait}.
|
38 |
|
|
|
39 |
|
|
@comment pthread.h
|
40 |
|
|
@comment POSIX
|
41 |
|
|
@deftypefun int pthread_create (pthread_t * @var{thread}, pthread_attr_t * @var{attr}, void * (*@var{start_routine})(void *), void * @var{arg})
|
42 |
|
|
@code{pthread_create} creates a new thread of control that executes
|
43 |
|
|
concurrently with the calling thread. The new thread calls the
|
44 |
|
|
function @var{start_routine}, passing it @var{arg} as first argument. The
|
45 |
|
|
new thread terminates either explicitly, by calling @code{pthread_exit},
|
46 |
|
|
or implicitly, by returning from the @var{start_routine} function. The
|
47 |
|
|
latter case is equivalent to calling @code{pthread_exit} with the result
|
48 |
|
|
returned by @var{start_routine} as exit code.
|
49 |
|
|
|
50 |
|
|
The @var{attr} argument specifies thread attributes to be applied to the
|
51 |
|
|
new thread. @xref{Thread Attributes}, for details. The @var{attr}
|
52 |
|
|
argument can also be @code{NULL}, in which case default attributes are
|
53 |
|
|
used: the created thread is joinable (not detached) and has an ordinary
|
54 |
|
|
(not realtime) scheduling policy.
|
55 |
|
|
|
56 |
|
|
On success, the identifier of the newly created thread is stored in the
|
57 |
|
|
location pointed by the @var{thread} argument, and a 0 is returned. On
|
58 |
|
|
error, a non-zero error code is returned.
|
59 |
|
|
|
60 |
|
|
This function may return the following errors:
|
61 |
|
|
@table @code
|
62 |
|
|
@item EAGAIN
|
63 |
|
|
Not enough system resources to create a process for the new thread,
|
64 |
|
|
or more than @code{PTHREAD_THREADS_MAX} threads are already active.
|
65 |
|
|
@end table
|
66 |
|
|
@end deftypefun
|
67 |
|
|
|
68 |
|
|
@comment pthread.h
|
69 |
|
|
@comment POSIX
|
70 |
|
|
@deftypefun void pthread_exit (void *@var{retval})
|
71 |
|
|
@code{pthread_exit} terminates the execution of the calling thread. All
|
72 |
|
|
cleanup handlers (@pxref{Cleanup Handlers}) that have been set for the
|
73 |
|
|
calling thread with @code{pthread_cleanup_push} are executed in reverse
|
74 |
|
|
order (the most recently pushed handler is executed first). Finalization
|
75 |
|
|
functions for thread-specific data are then called for all keys that
|
76 |
|
|
have non-@code{NULL} values associated with them in the calling thread
|
77 |
|
|
(@pxref{Thread-Specific Data}). Finally, execution of the calling
|
78 |
|
|
thread is stopped.
|
79 |
|
|
|
80 |
|
|
The @var{retval} argument is the return value of the thread. It can be
|
81 |
|
|
retrieved from another thread using @code{pthread_join}.
|
82 |
|
|
|
83 |
|
|
The @code{pthread_exit} function never returns.
|
84 |
|
|
@end deftypefun
|
85 |
|
|
|
86 |
|
|
@comment pthread.h
|
87 |
|
|
@comment POSIX
|
88 |
|
|
@deftypefun int pthread_cancel (pthread_t @var{thread})
|
89 |
|
|
|
90 |
|
|
@code{pthread_cancel} sends a cancellation request to the thread denoted
|
91 |
|
|
by the @var{thread} argument. If there is no such thread,
|
92 |
|
|
@code{pthread_cancel} fails and returns @code{ESRCH}. Otherwise it
|
93 |
|
|
returns 0. @xref{Cancellation}, for details.
|
94 |
|
|
@end deftypefun
|
95 |
|
|
|
96 |
|
|
@comment pthread.h
|
97 |
|
|
@comment POSIX
|
98 |
|
|
@deftypefun int pthread_join (pthread_t @var{th}, void **thread_@var{return})
|
99 |
|
|
@code{pthread_join} suspends the execution of the calling thread until
|
100 |
|
|
the thread identified by @var{th} terminates, either by calling
|
101 |
|
|
@code{pthread_exit} or by being cancelled.
|
102 |
|
|
|
103 |
|
|
If @var{thread_return} is not @code{NULL}, the return value of @var{th}
|
104 |
|
|
is stored in the location pointed to by @var{thread_return}. The return
|
105 |
|
|
value of @var{th} is either the argument it gave to @code{pthread_exit},
|
106 |
|
|
or @code{PTHREAD_CANCELED} if @var{th} was cancelled.
|
107 |
|
|
|
108 |
|
|
The joined thread @code{th} must be in the joinable state: it must not
|
109 |
|
|
have been detached using @code{pthread_detach} or the
|
110 |
|
|
@code{PTHREAD_CREATE_DETACHED} attribute to @code{pthread_create}.
|
111 |
|
|
|
112 |
|
|
When a joinable thread terminates, its memory resources (thread
|
113 |
|
|
descriptor and stack) are not deallocated until another thread performs
|
114 |
|
|
@code{pthread_join} on it. Therefore, @code{pthread_join} must be called
|
115 |
|
|
once for each joinable thread created to avoid memory leaks.
|
116 |
|
|
|
117 |
|
|
At most one thread can wait for the termination of a given
|
118 |
|
|
thread. Calling @code{pthread_join} on a thread @var{th} on which
|
119 |
|
|
another thread is already waiting for termination returns an error.
|
120 |
|
|
|
121 |
|
|
@code{pthread_join} is a cancellation point. If a thread is canceled
|
122 |
|
|
while suspended in @code{pthread_join}, the thread execution resumes
|
123 |
|
|
immediately and the cancellation is executed without waiting for the
|
124 |
|
|
@var{th} thread to terminate. If cancellation occurs during
|
125 |
|
|
@code{pthread_join}, the @var{th} thread remains not joined.
|
126 |
|
|
|
127 |
|
|
On success, the return value of @var{th} is stored in the location
|
128 |
|
|
pointed to by @var{thread_return}, and 0 is returned. On error, one of
|
129 |
|
|
the following values is returned:
|
130 |
|
|
@table @code
|
131 |
|
|
@item ESRCH
|
132 |
|
|
No thread could be found corresponding to that specified by @var{th}.
|
133 |
|
|
@item EINVAL
|
134 |
|
|
The @var{th} thread has been detached, or another thread is already
|
135 |
|
|
waiting on termination of @var{th}.
|
136 |
|
|
@item EDEADLK
|
137 |
|
|
The @var{th} argument refers to the calling thread.
|
138 |
|
|
@end table
|
139 |
|
|
@end deftypefun
|
140 |
|
|
|
141 |
|
|
@node Thread Attributes
|
142 |
|
|
@section Thread Attributes
|
143 |
|
|
|
144 |
|
|
@comment pthread.h
|
145 |
|
|
@comment POSIX
|
146 |
|
|
|
147 |
|
|
Threads have a number of attributes that may be set at creation time.
|
148 |
|
|
This is done by filling a thread attribute object @var{attr} of type
|
149 |
|
|
@code{pthread_attr_t}, then passing it as second argument to
|
150 |
|
|
@code{pthread_create}. Passing @code{NULL} is equivalent to passing a
|
151 |
|
|
thread attribute object with all attributes set to their default values.
|
152 |
|
|
|
153 |
|
|
Attribute objects are consulted only when creating a new thread. The
|
154 |
|
|
same attribute object can be used for creating several threads.
|
155 |
|
|
Modifying an attribute object after a call to @code{pthread_create} does
|
156 |
|
|
not change the attributes of the thread previously created.
|
157 |
|
|
|
158 |
|
|
@comment pthread.h
|
159 |
|
|
@comment POSIX
|
160 |
|
|
@deftypefun int pthread_attr_init (pthread_attr_t *@var{attr})
|
161 |
|
|
@code{pthread_attr_init} initializes the thread attribute object
|
162 |
|
|
@var{attr} and fills it with default values for the attributes. (The
|
163 |
|
|
default values are listed below for each attribute.)
|
164 |
|
|
|
165 |
|
|
Each attribute @var{attrname} (see below for a list of all attributes)
|
166 |
|
|
can be individually set using the function
|
167 |
|
|
@code{pthread_attr_set@var{attrname}} and retrieved using the function
|
168 |
|
|
@code{pthread_attr_get@var{attrname}}.
|
169 |
|
|
@end deftypefun
|
170 |
|
|
|
171 |
|
|
@comment pthread.h
|
172 |
|
|
@comment POSIX
|
173 |
|
|
@deftypefun int pthread_attr_destroy (pthread_attr_t *@var{attr})
|
174 |
|
|
@code{pthread_attr_destroy} destroys the attribute object pointed to by
|
175 |
|
|
@var{attr} releasing any resources associated with it. @var{attr} is
|
176 |
|
|
left in an undefined state, and you must not use it again in a call to
|
177 |
|
|
any pthreads function until it has been reinitialized.
|
178 |
|
|
@end deftypefun
|
179 |
|
|
|
180 |
|
|
@findex pthread_attr_setinheritsched
|
181 |
|
|
@findex pthread_attr_setschedparam
|
182 |
|
|
@findex pthread_attr_setschedpolicy
|
183 |
|
|
@findex pthread_attr_setscope
|
184 |
|
|
@comment pthread.h
|
185 |
|
|
@comment POSIX
|
186 |
|
|
@deftypefun int pthread_attr_set@var{attr} (pthread_attr_t *@var{obj}, int @var{value})
|
187 |
|
|
Set attribute @var{attr} to @var{value} in the attribute object pointed
|
188 |
|
|
to by @var{obj}. See below for a list of possible attributes and the
|
189 |
|
|
values they can take.
|
190 |
|
|
|
191 |
|
|
On success, these functions return 0. If @var{value} is not meaningful
|
192 |
|
|
for the @var{attr} being modified, they will return the error code
|
193 |
|
|
@code{EINVAL}. Some of the functions have other failure modes; see
|
194 |
|
|
below.
|
195 |
|
|
@end deftypefun
|
196 |
|
|
|
197 |
|
|
@findex pthread_attr_getinheritsched
|
198 |
|
|
@findex pthread_attr_getschedparam
|
199 |
|
|
@findex pthread_attr_getschedpolicy
|
200 |
|
|
@findex pthread_attr_getscope
|
201 |
|
|
@comment pthread.h
|
202 |
|
|
@comment POSIX
|
203 |
|
|
@deftypefun int pthread_attr_get@var{attr} (const pthread_attr_t *@var{obj}, int *@var{value})
|
204 |
|
|
Store the current setting of @var{attr} in @var{obj} into the variable
|
205 |
|
|
pointed to by @var{value}.
|
206 |
|
|
|
207 |
|
|
These functions always return 0.
|
208 |
|
|
@end deftypefun
|
209 |
|
|
|
210 |
|
|
The following thread attributes are supported:
|
211 |
|
|
@table @samp
|
212 |
|
|
@item detachstate
|
213 |
|
|
Choose whether the thread is created in the joinable state (value
|
214 |
|
|
@code{PTHREAD_CREATE_JOINABLE}) or in the detached state
|
215 |
|
|
(@code{PTHREAD_CREATE_DETACHED}). The default is
|
216 |
|
|
@code{PTHREAD_CREATE_JOINABLE}.
|
217 |
|
|
|
218 |
|
|
In the joinable state, another thread can synchronize on the thread
|
219 |
|
|
termination and recover its termination code using @code{pthread_join},
|
220 |
|
|
but some of the thread resources are kept allocated after the thread
|
221 |
|
|
terminates, and reclaimed only when another thread performs
|
222 |
|
|
@code{pthread_join} on that thread.
|
223 |
|
|
|
224 |
|
|
In the detached state, the thread resources are immediately freed when
|
225 |
|
|
it terminates, but @code{pthread_join} cannot be used to synchronize on
|
226 |
|
|
the thread termination.
|
227 |
|
|
|
228 |
|
|
A thread created in the joinable state can later be put in the detached
|
229 |
|
|
thread using @code{pthread_detach}.
|
230 |
|
|
|
231 |
|
|
@item schedpolicy
|
232 |
|
|
Select the scheduling policy for the thread: one of @code{SCHED_OTHER}
|
233 |
|
|
(regular, non-realtime scheduling), @code{SCHED_RR} (realtime,
|
234 |
|
|
round-robin) or @code{SCHED_FIFO} (realtime, first-in first-out).
|
235 |
|
|
The default is @code{SCHED_OTHER}.
|
236 |
|
|
@c Not doc'd in our manual: FIXME.
|
237 |
|
|
@c See @code{sched_setpolicy} for more information on scheduling policies.
|
238 |
|
|
|
239 |
|
|
The realtime scheduling policies @code{SCHED_RR} and @code{SCHED_FIFO}
|
240 |
|
|
are available only to processes with superuser privileges.
|
241 |
|
|
@code{pthread_attr_setschedparam} will fail and return @code{ENOTSUP} if
|
242 |
|
|
you try to set a realtime policy when you are unprivileged.
|
243 |
|
|
|
244 |
|
|
The scheduling policy of a thread can be changed after creation with
|
245 |
|
|
@code{pthread_setschedparam}.
|
246 |
|
|
|
247 |
|
|
@item schedparam
|
248 |
|
|
Change the scheduling parameter (the scheduling priority)
|
249 |
|
|
for the thread. The default is 0.
|
250 |
|
|
|
251 |
|
|
This attribute is not significant if the scheduling policy is
|
252 |
|
|
@code{SCHED_OTHER}; it only matters for the realtime policies
|
253 |
|
|
@code{SCHED_RR} and @code{SCHED_FIFO}.
|
254 |
|
|
|
255 |
|
|
The scheduling priority of a thread can be changed after creation with
|
256 |
|
|
@code{pthread_setschedparam}.
|
257 |
|
|
|
258 |
|
|
@item inheritsched
|
259 |
|
|
Choose whether the scheduling policy and scheduling parameter for the
|
260 |
|
|
newly created thread are determined by the values of the
|
261 |
|
|
@var{schedpolicy} and @var{schedparam} attributes (value
|
262 |
|
|
@code{PTHREAD_EXPLICIT_SCHED}) or are inherited from the parent thread
|
263 |
|
|
(value @code{PTHREAD_INHERIT_SCHED}). The default is
|
264 |
|
|
@code{PTHREAD_EXPLICIT_SCHED}.
|
265 |
|
|
|
266 |
|
|
@item scope
|
267 |
|
|
Choose the scheduling contention scope for the created thread. The
|
268 |
|
|
default is @code{PTHREAD_SCOPE_SYSTEM}, meaning that the threads contend
|
269 |
|
|
for CPU time with all processes running on the machine. In particular,
|
270 |
|
|
thread priorities are interpreted relative to the priorities of all
|
271 |
|
|
other processes on the machine. The other possibility,
|
272 |
|
|
@code{PTHREAD_SCOPE_PROCESS}, means that scheduling contention occurs
|
273 |
|
|
only between the threads of the running process: thread priorities are
|
274 |
|
|
interpreted relative to the priorities of the other threads of the
|
275 |
|
|
process, regardless of the priorities of other processes.
|
276 |
|
|
|
277 |
|
|
@code{PTHREAD_SCOPE_PROCESS} is not supported in LinuxThreads. If you
|
278 |
|
|
try to set the scope to this value @code{pthread_attr_setscope} will
|
279 |
|
|
fail and return @code{ENOTSUP}.
|
280 |
|
|
@end table
|
281 |
|
|
|
282 |
|
|
@node Cancellation
|
283 |
|
|
@section Cancellation
|
284 |
|
|
|
285 |
|
|
Cancellation is the mechanism by which a thread can terminate the
|
286 |
|
|
execution of another thread. More precisely, a thread can send a
|
287 |
|
|
cancellation request to another thread. Depending on its settings, the
|
288 |
|
|
target thread can then either ignore the request, honor it immediately,
|
289 |
|
|
or defer it till it reaches a cancellation point. When threads are
|
290 |
|
|
first created by @code{pthread_create}, they always defer cancellation
|
291 |
|
|
requests.
|
292 |
|
|
|
293 |
|
|
When a thread eventually honors a cancellation request, it behaves as if
|
294 |
|
|
@code{pthread_exit(PTHREAD_CANCELED)} was called. All cleanup handlers
|
295 |
|
|
are executed in reverse order, finalization functions for
|
296 |
|
|
thread-specific data are called, and finally the thread stops executing.
|
297 |
|
|
If the cancelled thread was joinable, the return value
|
298 |
|
|
@code{PTHREAD_CANCELED} is provided to whichever thread calls
|
299 |
|
|
@var{pthread_join} on it. See @code{pthread_exit} for more information.
|
300 |
|
|
|
301 |
|
|
Cancellation points are the points where the thread checks for pending
|
302 |
|
|
cancellation requests and performs them. The POSIX threads functions
|
303 |
|
|
@code{pthread_join}, @code{pthread_cond_wait},
|
304 |
|
|
@code{pthread_cond_timedwait}, @code{pthread_testcancel},
|
305 |
|
|
@code{sem_wait}, and @code{sigwait} are cancellation points. In
|
306 |
|
|
addition, these system calls are cancellation points:
|
307 |
|
|
|
308 |
|
|
@multitable @columnfractions .33 .33 .33
|
309 |
|
|
@item @t{accept} @tab @t{open} @tab @t{sendmsg}
|
310 |
|
|
@item @t{close} @tab @t{pause} @tab @t{sendto}
|
311 |
|
|
@item @t{connect} @tab @t{read} @tab @t{system}
|
312 |
|
|
@item @t{fcntl} @tab @t{recv} @tab @t{tcdrain}
|
313 |
|
|
@item @t{fsync} @tab @t{recvfrom} @tab @t{wait}
|
314 |
|
|
@item @t{lseek} @tab @t{recvmsg} @tab @t{waitpid}
|
315 |
|
|
@item @t{msync} @tab @t{send} @tab @t{write}
|
316 |
|
|
@item @t{nanosleep}
|
317 |
|
|
@end multitable
|
318 |
|
|
|
319 |
|
|
@noindent
|
320 |
|
|
All library functions that call these functions (such as
|
321 |
|
|
@code{printf}) are also cancellation points.
|
322 |
|
|
|
323 |
|
|
@comment pthread.h
|
324 |
|
|
@comment POSIX
|
325 |
|
|
@deftypefun int pthread_setcancelstate (int @var{state}, int *@var{oldstate})
|
326 |
|
|
@code{pthread_setcancelstate} changes the cancellation state for the
|
327 |
|
|
calling thread -- that is, whether cancellation requests are ignored or
|
328 |
|
|
not. The @var{state} argument is the new cancellation state: either
|
329 |
|
|
@code{PTHREAD_CANCEL_ENABLE} to enable cancellation, or
|
330 |
|
|
@code{PTHREAD_CANCEL_DISABLE} to disable cancellation (cancellation
|
331 |
|
|
requests are ignored).
|
332 |
|
|
|
333 |
|
|
If @var{oldstate} is not @code{NULL}, the previous cancellation state is
|
334 |
|
|
stored in the location pointed to by @var{oldstate}, and can thus be
|
335 |
|
|
restored later by another call to @code{pthread_setcancelstate}.
|
336 |
|
|
|
337 |
|
|
If the @var{state} argument is not @code{PTHREAD_CANCEL_ENABLE} or
|
338 |
|
|
@code{PTHREAD_CANCEL_DISABLE}, @code{pthread_setcancelstate} fails and
|
339 |
|
|
returns @code{EINVAL}. Otherwise it returns 0.
|
340 |
|
|
@end deftypefun
|
341 |
|
|
|
342 |
|
|
@comment pthread.h
|
343 |
|
|
@comment POSIX
|
344 |
|
|
@deftypefun int pthread_setcanceltype (int @var{type}, int *@var{oldtype})
|
345 |
|
|
@code{pthread_setcanceltype} changes the type of responses to
|
346 |
|
|
cancellation requests for the calling thread: asynchronous (immediate)
|
347 |
|
|
or deferred. The @var{type} argument is the new cancellation type:
|
348 |
|
|
either @code{PTHREAD_CANCEL_ASYNCHRONOUS} to cancel the calling thread
|
349 |
|
|
as soon as the cancellation request is received, or
|
350 |
|
|
@code{PTHREAD_CANCEL_DEFERRED} to keep the cancellation request pending
|
351 |
|
|
until the next cancellation point. If @var{oldtype} is not @code{NULL},
|
352 |
|
|
the previous cancellation state is stored in the location pointed to by
|
353 |
|
|
@var{oldtype}, and can thus be restored later by another call to
|
354 |
|
|
@code{pthread_setcanceltype}.
|
355 |
|
|
|
356 |
|
|
If the @var{type} argument is not @code{PTHREAD_CANCEL_DEFERRED} or
|
357 |
|
|
@code{PTHREAD_CANCEL_ASYNCHRONOUS}, @code{pthread_setcanceltype} fails
|
358 |
|
|
and returns @code{EINVAL}. Otherwise it returns 0.
|
359 |
|
|
@end deftypefun
|
360 |
|
|
|
361 |
|
|
@comment pthread.h
|
362 |
|
|
@comment POSIX
|
363 |
|
|
@deftypefun void pthread_testcancel (@var{void})
|
364 |
|
|
@code{pthread_testcancel} does nothing except testing for pending
|
365 |
|
|
cancellation and executing it. Its purpose is to introduce explicit
|
366 |
|
|
checks for cancellation in long sequences of code that do not call
|
367 |
|
|
cancellation point functions otherwise.
|
368 |
|
|
@end deftypefun
|
369 |
|
|
|
370 |
|
|
@node Cleanup Handlers
|
371 |
|
|
@section Cleanup Handlers
|
372 |
|
|
|
373 |
|
|
Cleanup handlers are functions that get called when a thread terminates,
|
374 |
|
|
either by calling @code{pthread_exit} or because of
|
375 |
|
|
cancellation. Cleanup handlers are installed and removed following a
|
376 |
|
|
stack-like discipline.
|
377 |
|
|
|
378 |
|
|
The purpose of cleanup handlers is to free the resources that a thread
|
379 |
|
|
may hold at the time it terminates. In particular, if a thread exits or
|
380 |
|
|
is cancelled while it owns a locked mutex, the mutex will remain locked
|
381 |
|
|
forever and prevent other threads from executing normally. The best way
|
382 |
|
|
to avoid this is, just before locking the mutex, to install a cleanup
|
383 |
|
|
handler whose effect is to unlock the mutex. Cleanup handlers can be
|
384 |
|
|
used similarly to free blocks allocated with @code{malloc} or close file
|
385 |
|
|
descriptors on thread termination.
|
386 |
|
|
|
387 |
|
|
Here is how to lock a mutex @var{mut} in such a way that it will be
|
388 |
|
|
unlocked if the thread is canceled while @var{mut} is locked:
|
389 |
|
|
|
390 |
|
|
@smallexample
|
391 |
|
|
pthread_cleanup_push(pthread_mutex_unlock, (void *) &mut);
|
392 |
|
|
pthread_mutex_lock(&mut);
|
393 |
|
|
/* do some work */
|
394 |
|
|
pthread_mutex_unlock(&mut);
|
395 |
|
|
pthread_cleanup_pop(0);
|
396 |
|
|
@end smallexample
|
397 |
|
|
|
398 |
|
|
Equivalently, the last two lines can be replaced by
|
399 |
|
|
|
400 |
|
|
@smallexample
|
401 |
|
|
pthread_cleanup_pop(1);
|
402 |
|
|
@end smallexample
|
403 |
|
|
|
404 |
|
|
Notice that the code above is safe only in deferred cancellation mode
|
405 |
|
|
(see @code{pthread_setcanceltype}). In asynchronous cancellation mode, a
|
406 |
|
|
cancellation can occur between @code{pthread_cleanup_push} and
|
407 |
|
|
@code{pthread_mutex_lock}, or between @code{pthread_mutex_unlock} and
|
408 |
|
|
@code{pthread_cleanup_pop}, resulting in both cases in the thread trying
|
409 |
|
|
to unlock a mutex not locked by the current thread. This is the main
|
410 |
|
|
reason why asynchronous cancellation is difficult to use.
|
411 |
|
|
|
412 |
|
|
If the code above must also work in asynchronous cancellation mode,
|
413 |
|
|
then it must switch to deferred mode for locking and unlocking the
|
414 |
|
|
mutex:
|
415 |
|
|
|
416 |
|
|
@smallexample
|
417 |
|
|
pthread_setcanceltype(PTHREAD_CANCEL_DEFERRED, &oldtype);
|
418 |
|
|
pthread_cleanup_push(pthread_mutex_unlock, (void *) &mut);
|
419 |
|
|
pthread_mutex_lock(&mut);
|
420 |
|
|
/* do some work */
|
421 |
|
|
pthread_cleanup_pop(1);
|
422 |
|
|
pthread_setcanceltype(oldtype, NULL);
|
423 |
|
|
@end smallexample
|
424 |
|
|
|
425 |
|
|
The code above can be rewritten in a more compact and efficient way,
|
426 |
|
|
using the non-portable functions @code{pthread_cleanup_push_defer_np}
|
427 |
|
|
and @code{pthread_cleanup_pop_restore_np}:
|
428 |
|
|
|
429 |
|
|
@smallexample
|
430 |
|
|
pthread_cleanup_push_defer_np(pthread_mutex_unlock, (void *) &mut);
|
431 |
|
|
pthread_mutex_lock(&mut);
|
432 |
|
|
/* do some work */
|
433 |
|
|
pthread_cleanup_pop_restore_np(1);
|
434 |
|
|
@end smallexample
|
435 |
|
|
|
436 |
|
|
@comment pthread.h
|
437 |
|
|
@comment POSIX
|
438 |
|
|
@deftypefun void pthread_cleanup_push (void (*@var{routine}) (void *), void *@var{arg})
|
439 |
|
|
|
440 |
|
|
@code{pthread_cleanup_push} installs the @var{routine} function with
|
441 |
|
|
argument @var{arg} as a cleanup handler. From this point on to the
|
442 |
|
|
matching @code{pthread_cleanup_pop}, the function @var{routine} will be
|
443 |
|
|
called with arguments @var{arg} when the thread terminates, either
|
444 |
|
|
through @code{pthread_exit} or by cancellation. If several cleanup
|
445 |
|
|
handlers are active at that point, they are called in LIFO order: the
|
446 |
|
|
most recently installed handler is called first.
|
447 |
|
|
@end deftypefun
|
448 |
|
|
|
449 |
|
|
@comment pthread.h
|
450 |
|
|
@comment POSIX
|
451 |
|
|
@deftypefun void pthread_cleanup_pop (int @var{execute})
|
452 |
|
|
@code{pthread_cleanup_pop} removes the most recently installed cleanup
|
453 |
|
|
handler. If the @var{execute} argument is not 0, it also executes the
|
454 |
|
|
handler, by calling the @var{routine} function with arguments
|
455 |
|
|
@var{arg}. If the @var{execute} argument is 0, the handler is only
|
456 |
|
|
removed but not executed.
|
457 |
|
|
@end deftypefun
|
458 |
|
|
|
459 |
|
|
Matching pairs of @code{pthread_cleanup_push} and
|
460 |
|
|
@code{pthread_cleanup_pop} must occur in the same function, at the same
|
461 |
|
|
level of block nesting. Actually, @code{pthread_cleanup_push} and
|
462 |
|
|
@code{pthread_cleanup_pop} are macros, and the expansion of
|
463 |
|
|
@code{pthread_cleanup_push} introduces an open brace @code{@{} with the
|
464 |
|
|
matching closing brace @code{@}} being introduced by the expansion of the
|
465 |
|
|
matching @code{pthread_cleanup_pop}.
|
466 |
|
|
|
467 |
|
|
@comment pthread.h
|
468 |
|
|
@comment GNU
|
469 |
|
|
@deftypefun void pthread_cleanup_push_defer_np (void (*@var{routine}) (void *), void *@var{arg})
|
470 |
|
|
@code{pthread_cleanup_push_defer_np} is a non-portable extension that
|
471 |
|
|
combines @code{pthread_cleanup_push} and @code{pthread_setcanceltype}.
|
472 |
|
|
It pushes a cleanup handler just as @code{pthread_cleanup_push} does,
|
473 |
|
|
but also saves the current cancellation type and sets it to deferred
|
474 |
|
|
cancellation. This ensures that the cleanup mechanism is effective even
|
475 |
|
|
if the thread was initially in asynchronous cancellation mode.
|
476 |
|
|
@end deftypefun
|
477 |
|
|
|
478 |
|
|
@comment pthread.h
|
479 |
|
|
@comment GNU
|
480 |
|
|
@deftypefun void pthread_cleanup_pop_restore_np (int @var{execute})
|
481 |
|
|
@code{pthread_cleanup_pop_restore_np} pops a cleanup handler introduced
|
482 |
|
|
by @code{pthread_cleanup_push_defer_np}, and restores the cancellation
|
483 |
|
|
type to its value at the time @code{pthread_cleanup_push_defer_np} was
|
484 |
|
|
called.
|
485 |
|
|
@end deftypefun
|
486 |
|
|
|
487 |
|
|
@code{pthread_cleanup_push_defer_np} and
|
488 |
|
|
@code{pthread_cleanup_pop_restore_np} must occur in matching pairs, at
|
489 |
|
|
the same level of block nesting.
|
490 |
|
|
|
491 |
|
|
The sequence
|
492 |
|
|
|
493 |
|
|
@smallexample
|
494 |
|
|
pthread_cleanup_push_defer_np(routine, arg);
|
495 |
|
|
...
|
496 |
|
|
pthread_cleanup_pop_defer_np(execute);
|
497 |
|
|
@end smallexample
|
498 |
|
|
|
499 |
|
|
@noindent
|
500 |
|
|
is functionally equivalent to (but more compact and efficient than)
|
501 |
|
|
|
502 |
|
|
@smallexample
|
503 |
|
|
@{
|
504 |
|
|
int oldtype;
|
505 |
|
|
pthread_setcanceltype(PTHREAD_CANCEL_DEFERRED, &oldtype);
|
506 |
|
|
pthread_cleanup_push(routine, arg);
|
507 |
|
|
...
|
508 |
|
|
pthread_cleanup_pop(execute);
|
509 |
|
|
pthread_setcanceltype(oldtype, NULL);
|
510 |
|
|
@}
|
511 |
|
|
@end smallexample
|
512 |
|
|
|
513 |
|
|
|
514 |
|
|
@node Mutexes
|
515 |
|
|
@section Mutexes
|
516 |
|
|
|
517 |
|
|
A mutex is a MUTual EXclusion device, and is useful for protecting
|
518 |
|
|
shared data structures from concurrent modifications, and implementing
|
519 |
|
|
critical sections and monitors.
|
520 |
|
|
|
521 |
|
|
A mutex has two possible states: unlocked (not owned by any thread),
|
522 |
|
|
and locked (owned by one thread). A mutex can never be owned by two
|
523 |
|
|
different threads simultaneously. A thread attempting to lock a mutex
|
524 |
|
|
that is already locked by another thread is suspended until the owning
|
525 |
|
|
thread unlocks the mutex first.
|
526 |
|
|
|
527 |
|
|
None of the mutex functions is a cancellation point, not even
|
528 |
|
|
@code{pthread_mutex_lock}, in spite of the fact that it can suspend a
|
529 |
|
|
thread for arbitrary durations. This way, the status of mutexes at
|
530 |
|
|
cancellation points is predictable, allowing cancellation handlers to
|
531 |
|
|
unlock precisely those mutexes that need to be unlocked before the
|
532 |
|
|
thread stops executing. Consequently, threads using deferred
|
533 |
|
|
cancellation should never hold a mutex for extended periods of time.
|
534 |
|
|
|
535 |
|
|
It is not safe to call mutex functions from a signal handler. In
|
536 |
|
|
particular, calling @code{pthread_mutex_lock} or
|
537 |
|
|
@code{pthread_mutex_unlock} from a signal handler may deadlock the
|
538 |
|
|
calling thread.
|
539 |
|
|
|
540 |
|
|
@comment pthread.h
|
541 |
|
|
@comment POSIX
|
542 |
|
|
@deftypefun int pthread_mutex_init (pthread_mutex_t *@var{mutex}, const pthread_mutexattr_t *@var{mutexattr})
|
543 |
|
|
|
544 |
|
|
@code{pthread_mutex_init} initializes the mutex object pointed to by
|
545 |
|
|
@var{mutex} according to the mutex attributes specified in @var{mutexattr}.
|
546 |
|
|
If @var{mutexattr} is @code{NULL}, default attributes are used instead.
|
547 |
|
|
|
548 |
|
|
The LinuxThreads implementation supports only one mutex attribute,
|
549 |
|
|
the @var{mutex kind}, which is either ``fast'', ``recursive'', or
|
550 |
|
|
``error checking''. The kind of a mutex determines whether
|
551 |
|
|
it can be locked again by a thread that already owns it.
|
552 |
|
|
The default kind is ``fast''.
|
553 |
|
|
|
554 |
|
|
Variables of type @code{pthread_mutex_t} can also be initialized
|
555 |
|
|
statically, using the constants @code{PTHREAD_MUTEX_INITIALIZER} (for
|
556 |
|
|
fast mutexes), @code{PTHREAD_RECURSIVE_MUTEX_INITIALIZER_NP} (for
|
557 |
|
|
recursive mutexes), and @code{PTHREAD_ERRORCHECK_MUTEX_INITIALIZER_NP}
|
558 |
|
|
(for error checking mutexes).
|
559 |
|
|
|
560 |
|
|
@code{pthread_mutex_init} always returns 0.
|
561 |
|
|
@end deftypefun
|
562 |
|
|
|
563 |
|
|
@comment pthread.h
|
564 |
|
|
@comment POSIX
|
565 |
|
|
@deftypefun int pthread_mutex_lock (pthread_mutex_t *mutex))
|
566 |
|
|
@code{pthread_mutex_lock} locks the given mutex. If the mutex is
|
567 |
|
|
currently unlocked, it becomes locked and owned by the calling thread,
|
568 |
|
|
and @code{pthread_mutex_lock} returns immediately. If the mutex is
|
569 |
|
|
already locked by another thread, @code{pthread_mutex_lock} suspends the
|
570 |
|
|
calling thread until the mutex is unlocked.
|
571 |
|
|
|
572 |
|
|
If the mutex is already locked by the calling thread, the behavior of
|
573 |
|
|
@code{pthread_mutex_lock} depends on the kind of the mutex. If the mutex
|
574 |
|
|
is of the ``fast'' kind, the calling thread is suspended. It will
|
575 |
|
|
remain suspended forever, because no other thread can unlock the mutex.
|
576 |
|
|
If the mutex is of the ``error checking'' kind, @code{pthread_mutex_lock}
|
577 |
|
|
returns immediately with the error code @code{EDEADLK}. If the mutex is
|
578 |
|
|
of the ``recursive'' kind, @code{pthread_mutex_lock} succeeds and
|
579 |
|
|
returns immediately, recording the number of times the calling thread
|
580 |
|
|
has locked the mutex. An equal number of @code{pthread_mutex_unlock}
|
581 |
|
|
operations must be performed before the mutex returns to the unlocked
|
582 |
|
|
state.
|
583 |
|
|
@end deftypefun
|
584 |
|
|
|
585 |
|
|
@comment pthread.h
|
586 |
|
|
@comment POSIX
|
587 |
|
|
@deftypefun int pthread_mutex_trylock (pthread_mutex_t *@var{mutex})
|
588 |
|
|
@code{pthread_mutex_trylock} behaves identically to
|
589 |
|
|
@code{pthread_mutex_lock}, except that it does not block the calling
|
590 |
|
|
thread if the mutex is already locked by another thread (or by the
|
591 |
|
|
calling thread in the case of a ``fast'' mutex). Instead,
|
592 |
|
|
@code{pthread_mutex_trylock} returns immediately with the error code
|
593 |
|
|
@code{EBUSY}.
|
594 |
|
|
@end deftypefun
|
595 |
|
|
|
596 |
|
|
@comment pthread.h
|
597 |
|
|
@comment POSIX
|
598 |
|
|
@deftypefun int pthread_mutex_unlock (pthread_mutex_t *@var{mutex})
|
599 |
|
|
@code{pthread_mutex_unlock} unlocks the given mutex. The mutex is
|
600 |
|
|
assumed to be locked and owned by the calling thread on entrance to
|
601 |
|
|
@code{pthread_mutex_unlock}. If the mutex is of the ``fast'' kind,
|
602 |
|
|
@code{pthread_mutex_unlock} always returns it to the unlocked state. If
|
603 |
|
|
it is of the ``recursive'' kind, it decrements the locking count of the
|
604 |
|
|
mutex (number of @code{pthread_mutex_lock} operations performed on it by
|
605 |
|
|
the calling thread), and only when this count reaches zero is the mutex
|
606 |
|
|
actually unlocked.
|
607 |
|
|
|
608 |
|
|
On ``error checking'' mutexes, @code{pthread_mutex_unlock} actually
|
609 |
|
|
checks at run-time that the mutex is locked on entrance, and that it was
|
610 |
|
|
locked by the same thread that is now calling
|
611 |
|
|
@code{pthread_mutex_unlock}. If these conditions are not met,
|
612 |
|
|
@code{pthread_mutex_unlock} returns @code{EPERM}, and the mutex remains
|
613 |
|
|
unchanged. ``Fast'' and ``recursive'' mutexes perform no such checks,
|
614 |
|
|
thus allowing a locked mutex to be unlocked by a thread other than its
|
615 |
|
|
owner. This is non-portable behavior and must not be relied upon.
|
616 |
|
|
@end deftypefun
|
617 |
|
|
|
618 |
|
|
@comment pthread.h
|
619 |
|
|
@comment POSIX
|
620 |
|
|
@deftypefun int pthread_mutex_destroy (pthread_mutex_t *@var{mutex})
|
621 |
|
|
@code{pthread_mutex_destroy} destroys a mutex object, freeing the
|
622 |
|
|
resources it might hold. The mutex must be unlocked on entrance. In the
|
623 |
|
|
LinuxThreads implementation, no resources are associated with mutex
|
624 |
|
|
objects, thus @code{pthread_mutex_destroy} actually does nothing except
|
625 |
|
|
checking that the mutex is unlocked.
|
626 |
|
|
|
627 |
|
|
If the mutex is locked by some thread, @code{pthread_mutex_destroy}
|
628 |
|
|
returns @code{EBUSY}. Otherwise it returns 0.
|
629 |
|
|
@end deftypefun
|
630 |
|
|
|
631 |
|
|
If any of the above functions (except @code{pthread_mutex_init})
|
632 |
|
|
is applied to an uninitialized mutex, they will simply return
|
633 |
|
|
@code{EINVAL} and do nothing.
|
634 |
|
|
|
635 |
|
|
A shared global variable @var{x} can be protected by a mutex as follows:
|
636 |
|
|
|
637 |
|
|
@smallexample
|
638 |
|
|
int x;
|
639 |
|
|
pthread_mutex_t mut = PTHREAD_MUTEX_INITIALIZER;
|
640 |
|
|
@end smallexample
|
641 |
|
|
|
642 |
|
|
All accesses and modifications to @var{x} should be bracketed by calls to
|
643 |
|
|
@code{pthread_mutex_lock} and @code{pthread_mutex_unlock} as follows:
|
644 |
|
|
|
645 |
|
|
@smallexample
|
646 |
|
|
pthread_mutex_lock(&mut);
|
647 |
|
|
/* operate on x */
|
648 |
|
|
pthread_mutex_unlock(&mut);
|
649 |
|
|
@end smallexample
|
650 |
|
|
|
651 |
|
|
Mutex attributes can be specified at mutex creation time, by passing a
|
652 |
|
|
mutex attribute object as second argument to @code{pthread_mutex_init}.
|
653 |
|
|
Passing @code{NULL} is equivalent to passing a mutex attribute object
|
654 |
|
|
with all attributes set to their default values.
|
655 |
|
|
|
656 |
|
|
@comment pthread.h
|
657 |
|
|
@comment POSIX
|
658 |
|
|
@deftypefun int pthread_mutexattr_init (pthread_mutexattr_t *@var{attr})
|
659 |
|
|
@code{pthread_mutexattr_init} initializes the mutex attribute object
|
660 |
|
|
@var{attr} and fills it with default values for the attributes.
|
661 |
|
|
|
662 |
|
|
This function always returns 0.
|
663 |
|
|
@end deftypefun
|
664 |
|
|
|
665 |
|
|
@comment pthread.h
|
666 |
|
|
@comment POSIX
|
667 |
|
|
@deftypefun int pthread_mutexattr_destroy (pthread_mutexattr_t *@var{attr})
|
668 |
|
|
@code{pthread_mutexattr_destroy} destroys a mutex attribute object,
|
669 |
|
|
which must not be reused until it is
|
670 |
|
|
reinitialized. @code{pthread_mutexattr_destroy} does nothing in the
|
671 |
|
|
LinuxThreads implementation.
|
672 |
|
|
|
673 |
|
|
This function always returns 0.
|
674 |
|
|
@end deftypefun
|
675 |
|
|
|
676 |
|
|
LinuxThreads supports only one mutex attribute: the mutex kind, which is
|
677 |
|
|
either @code{PTHREAD_MUTEX_FAST_NP} for ``fast'' mutexes,
|
678 |
|
|
@code{PTHREAD_MUTEX_RECURSIVE_NP} for ``recursive'' mutexes, or
|
679 |
|
|
@code{PTHREAD_MUTEX_ERRORCHECK_NP} for ``error checking'' mutexes. As
|
680 |
|
|
the @code{NP} suffix indicates, this is a non-portable extension to the
|
681 |
|
|
POSIX standard and should not be employed in portable programs.
|
682 |
|
|
|
683 |
|
|
The mutex kind determines what happens if a thread attempts to lock a
|
684 |
|
|
mutex it already owns with @code{pthread_mutex_lock}. If the mutex is of
|
685 |
|
|
the ``fast'' kind, @code{pthread_mutex_lock} simply suspends the calling
|
686 |
|
|
thread forever. If the mutex is of the ``error checking'' kind,
|
687 |
|
|
@code{pthread_mutex_lock} returns immediately with the error code
|
688 |
|
|
@code{EDEADLK}. If the mutex is of the ``recursive'' kind, the call to
|
689 |
|
|
@code{pthread_mutex_lock} returns immediately with a success return
|
690 |
|
|
code. The number of times the thread owning the mutex has locked it is
|
691 |
|
|
recorded in the mutex. The owning thread must call
|
692 |
|
|
@code{pthread_mutex_unlock} the same number of times before the mutex
|
693 |
|
|
returns to the unlocked state.
|
694 |
|
|
|
695 |
|
|
The default mutex kind is ``fast'', that is, @code{PTHREAD_MUTEX_FAST_NP}.
|
696 |
|
|
|
697 |
|
|
@comment pthread.h
|
698 |
|
|
@comment GNU
|
699 |
|
|
@deftypefun int pthread_mutexattr_setkind_np (pthread_mutexattr_t *@var{attr}, int @var{kind})
|
700 |
|
|
@code{pthread_mutexattr_setkind_np} sets the mutex kind attribute in
|
701 |
|
|
@var{attr} to the value specified by @var{kind}.
|
702 |
|
|
|
703 |
|
|
If @var{kind} is not @code{PTHREAD_MUTEX_FAST_NP},
|
704 |
|
|
@code{PTHREAD_MUTEX_RECURSIVE_NP}, or
|
705 |
|
|
@code{PTHREAD_MUTEX_ERRORCHECK_NP}, this function will return
|
706 |
|
|
@code{EINVAL} and leave @var{attr} unchanged.
|
707 |
|
|
@end deftypefun
|
708 |
|
|
|
709 |
|
|
@comment pthread.h
|
710 |
|
|
@comment GNU
|
711 |
|
|
@deftypefun int pthread_mutexattr_getkind_np (const pthread_mutexattr_t *@var{attr}, int *@var{kind})
|
712 |
|
|
@code{pthread_mutexattr_getkind_np} retrieves the current value of the
|
713 |
|
|
mutex kind attribute in @var{attr} and stores it in the location pointed
|
714 |
|
|
to by @var{kind}.
|
715 |
|
|
|
716 |
|
|
This function always returns 0.
|
717 |
|
|
@end deftypefun
|
718 |
|
|
|
719 |
|
|
@node Condition Variables
|
720 |
|
|
@section Condition Variables
|
721 |
|
|
|
722 |
|
|
A condition (short for ``condition variable'') is a synchronization
|
723 |
|
|
device that allows threads to suspend execution until some predicate on
|
724 |
|
|
shared data is satisfied. The basic operations on conditions are: signal
|
725 |
|
|
the condition (when the predicate becomes true), and wait for the
|
726 |
|
|
condition, suspending the thread execution until another thread signals
|
727 |
|
|
the condition.
|
728 |
|
|
|
729 |
|
|
A condition variable must always be associated with a mutex, to avoid
|
730 |
|
|
the race condition where a thread prepares to wait on a condition
|
731 |
|
|
variable and another thread signals the condition just before the first
|
732 |
|
|
thread actually waits on it.
|
733 |
|
|
|
734 |
|
|
@comment pthread.h
|
735 |
|
|
@comment POSIX
|
736 |
|
|
@deftypefun int pthread_cond_init (pthread_cond_t *@var{cond}, pthread_condattr_t *cond_@var{attr})
|
737 |
|
|
|
738 |
|
|
@code{pthread_cond_init} initializes the condition variable @var{cond},
|
739 |
|
|
using the condition attributes specified in @var{cond_attr}, or default
|
740 |
|
|
attributes if @var{cond_attr} is @code{NULL}. The LinuxThreads
|
741 |
|
|
implementation supports no attributes for conditions, hence the
|
742 |
|
|
@var{cond_attr} parameter is actually ignored.
|
743 |
|
|
|
744 |
|
|
Variables of type @code{pthread_cond_t} can also be initialized
|
745 |
|
|
statically, using the constant @code{PTHREAD_COND_INITIALIZER}.
|
746 |
|
|
|
747 |
|
|
This function always returns 0.
|
748 |
|
|
@end deftypefun
|
749 |
|
|
|
750 |
|
|
@comment pthread.h
|
751 |
|
|
@comment POSIX
|
752 |
|
|
@deftypefun int pthread_cond_signal (pthread_cond_t *@var{cond})
|
753 |
|
|
@code{pthread_cond_signal} restarts one of the threads that are waiting
|
754 |
|
|
on the condition variable @var{cond}. If no threads are waiting on
|
755 |
|
|
@var{cond}, nothing happens. If several threads are waiting on
|
756 |
|
|
@var{cond}, exactly one is restarted, but it is not specified which.
|
757 |
|
|
|
758 |
|
|
This function always returns 0.
|
759 |
|
|
@end deftypefun
|
760 |
|
|
|
761 |
|
|
@comment pthread.h
|
762 |
|
|
@comment POSIX
|
763 |
|
|
@deftypefun int pthread_cond_broadcast (pthread_cond_t *@var{cond})
|
764 |
|
|
@code{pthread_cond_broadcast} restarts all the threads that are waiting
|
765 |
|
|
on the condition variable @var{cond}. Nothing happens if no threads are
|
766 |
|
|
waiting on @var{cond}.
|
767 |
|
|
|
768 |
|
|
This function always returns 0.
|
769 |
|
|
@end deftypefun
|
770 |
|
|
|
771 |
|
|
@comment pthread.h
|
772 |
|
|
@comment POSIX
|
773 |
|
|
@deftypefun int pthread_cond_wait (pthread_cond_t *@var{cond}, pthread_mutex_t *@var{mutex})
|
774 |
|
|
@code{pthread_cond_wait} atomically unlocks the @var{mutex} (as per
|
775 |
|
|
@code{pthread_unlock_mutex}) and waits for the condition variable
|
776 |
|
|
@var{cond} to be signaled. The thread execution is suspended and does
|
777 |
|
|
not consume any CPU time until the condition variable is signaled. The
|
778 |
|
|
@var{mutex} must be locked by the calling thread on entrance to
|
779 |
|
|
@code{pthread_cond_wait}. Before returning to the calling thread,
|
780 |
|
|
@code{pthread_cond_wait} re-acquires @var{mutex} (as per
|
781 |
|
|
@code{pthread_lock_mutex}).
|
782 |
|
|
|
783 |
|
|
Unlocking the mutex and suspending on the condition variable is done
|
784 |
|
|
atomically. Thus, if all threads always acquire the mutex before
|
785 |
|
|
signaling the condition, this guarantees that the condition cannot be
|
786 |
|
|
signaled (and thus ignored) between the time a thread locks the mutex
|
787 |
|
|
and the time it waits on the condition variable.
|
788 |
|
|
|
789 |
|
|
This function always returns 0.
|
790 |
|
|
@end deftypefun
|
791 |
|
|
|
792 |
|
|
@comment pthread.h
|
793 |
|
|
@comment POSIX
|
794 |
|
|
@deftypefun int pthread_cond_timedwait (pthread_cond_t *@var{cond}, pthread_mutex_t *@var{mutex}, const struct timespec *@var{abstime})
|
795 |
|
|
@code{pthread_cond_timedwait} atomically unlocks @var{mutex} and waits
|
796 |
|
|
on @var{cond}, as @code{pthread_cond_wait} does, but it also bounds the
|
797 |
|
|
duration of the wait. If @var{cond} has not been signaled before time
|
798 |
|
|
@var{abstime}, the mutex @var{mutex} is re-acquired and
|
799 |
|
|
@code{pthread_cond_timedwait} returns the error code @code{ETIMEDOUT}.
|
800 |
|
|
The wait can also be interrupted by a signal; in that case
|
801 |
|
|
@code{pthread_cond_timedwait} returns @code{EINTR}.
|
802 |
|
|
|
803 |
|
|
The @var{abstime} parameter specifies an absolute time, with the same
|
804 |
|
|
origin as @code{time} and @code{gettimeofday}: an @var{abstime} of 0
|
805 |
|
|
corresponds to 00:00:00 GMT, January 1, 1970.
|
806 |
|
|
@end deftypefun
|
807 |
|
|
|
808 |
|
|
@comment pthread.h
|
809 |
|
|
@comment POSIX
|
810 |
|
|
@deftypefun int pthread_cond_destroy (pthread_cond_t *@var{cond})
|
811 |
|
|
@code{pthread_cond_destroy} destroys the condition variable @var{cond},
|
812 |
|
|
freeing the resources it might hold. If any threads are waiting on the
|
813 |
|
|
condition variable, @code{pthread_cond_destroy} leaves @var{cond}
|
814 |
|
|
untouched and returns @code{EBUSY}. Otherwise it returns 0, and
|
815 |
|
|
@var{cond} must not be used again until it is reinitialized.
|
816 |
|
|
|
817 |
|
|
In the LinuxThreads implementation, no resources are associated with
|
818 |
|
|
condition variables, so @code{pthread_cond_destroy} actually does
|
819 |
|
|
nothing.
|
820 |
|
|
@end deftypefun
|
821 |
|
|
|
822 |
|
|
@code{pthread_cond_wait} and @code{pthread_cond_timedwait} are
|
823 |
|
|
cancellation points. If a thread is cancelled while suspended in one of
|
824 |
|
|
these functions, the thread immediately resumes execution, relocks the
|
825 |
|
|
mutex specified by @var{mutex}, and finally executes the cancellation.
|
826 |
|
|
Consequently, cleanup handlers are assured that @var{mutex} is locked
|
827 |
|
|
when they are called.
|
828 |
|
|
|
829 |
|
|
It is not safe to call the condition variable functions from a signal
|
830 |
|
|
handler. In particular, calling @code{pthread_cond_signal} or
|
831 |
|
|
@code{pthread_cond_broadcast} from a signal handler may deadlock the
|
832 |
|
|
calling thread.
|
833 |
|
|
|
834 |
|
|
Consider two shared variables @var{x} and @var{y}, protected by the
|
835 |
|
|
mutex @var{mut}, and a condition variable @var{cond} that is to be
|
836 |
|
|
signaled whenever @var{x} becomes greater than @var{y}.
|
837 |
|
|
|
838 |
|
|
@smallexample
|
839 |
|
|
int x,y;
|
840 |
|
|
pthread_mutex_t mut = PTHREAD_MUTEX_INITIALIZER;
|
841 |
|
|
pthread_cond_t cond = PTHREAD_COND_INITIALIZER;
|
842 |
|
|
@end smallexample
|
843 |
|
|
|
844 |
|
|
Waiting until @var{x} is greater than @var{y} is performed as follows:
|
845 |
|
|
|
846 |
|
|
@smallexample
|
847 |
|
|
pthread_mutex_lock(&mut);
|
848 |
|
|
while (x <= y) @{
|
849 |
|
|
pthread_cond_wait(&cond, &mut);
|
850 |
|
|
@}
|
851 |
|
|
/* operate on x and y */
|
852 |
|
|
pthread_mutex_unlock(&mut);
|
853 |
|
|
@end smallexample
|
854 |
|
|
|
855 |
|
|
Modifications on @var{x} and @var{y} that may cause @var{x} to become greater than
|
856 |
|
|
@var{y} should signal the condition if needed:
|
857 |
|
|
|
858 |
|
|
@smallexample
|
859 |
|
|
pthread_mutex_lock(&mut);
|
860 |
|
|
/* modify x and y */
|
861 |
|
|
if (x > y) pthread_cond_broadcast(&cond);
|
862 |
|
|
pthread_mutex_unlock(&mut);
|
863 |
|
|
@end smallexample
|
864 |
|
|
|
865 |
|
|
If it can be proved that at most one waiting thread needs to be waken
|
866 |
|
|
up (for instance, if there are only two threads communicating through
|
867 |
|
|
@var{x} and @var{y}), @code{pthread_cond_signal} can be used as a slightly more
|
868 |
|
|
efficient alternative to @code{pthread_cond_broadcast}. In doubt, use
|
869 |
|
|
@code{pthread_cond_broadcast}.
|
870 |
|
|
|
871 |
|
|
To wait for @var{x} to becomes greater than @var{y} with a timeout of 5
|
872 |
|
|
seconds, do:
|
873 |
|
|
|
874 |
|
|
@smallexample
|
875 |
|
|
struct timeval now;
|
876 |
|
|
struct timespec timeout;
|
877 |
|
|
int retcode;
|
878 |
|
|
|
879 |
|
|
pthread_mutex_lock(&mut);
|
880 |
|
|
gettimeofday(&now);
|
881 |
|
|
timeout.tv_sec = now.tv_sec + 5;
|
882 |
|
|
timeout.tv_nsec = now.tv_usec * 1000;
|
883 |
|
|
retcode = 0;
|
884 |
|
|
while (x <= y && retcode != ETIMEDOUT) @{
|
885 |
|
|
retcode = pthread_cond_timedwait(&cond, &mut, &timeout);
|
886 |
|
|
@}
|
887 |
|
|
if (retcode == ETIMEDOUT) @{
|
888 |
|
|
/* timeout occurred */
|
889 |
|
|
@} else @{
|
890 |
|
|
/* operate on x and y */
|
891 |
|
|
@}
|
892 |
|
|
pthread_mutex_unlock(&mut);
|
893 |
|
|
@end smallexample
|
894 |
|
|
|
895 |
|
|
Condition attributes can be specified at condition creation time, by
|
896 |
|
|
passing a condition attribute object as second argument to
|
897 |
|
|
@code{pthread_cond_init}. Passing @code{NULL} is equivalent to passing
|
898 |
|
|
a condition attribute object with all attributes set to their default
|
899 |
|
|
values.
|
900 |
|
|
|
901 |
|
|
The LinuxThreads implementation supports no attributes for
|
902 |
|
|
conditions. The functions on condition attributes are included only for
|
903 |
|
|
compliance with the POSIX standard.
|
904 |
|
|
|
905 |
|
|
@comment pthread.h
|
906 |
|
|
@comment POSIX
|
907 |
|
|
@deftypefun int pthread_condattr_init (pthread_condattr_t *@var{attr})
|
908 |
|
|
@deftypefunx int pthread_condattr_destroy (pthread_condattr_t *@var{attr})
|
909 |
|
|
@code{pthread_condattr_init} initializes the condition attribute object
|
910 |
|
|
@var{attr} and fills it with default values for the attributes.
|
911 |
|
|
@code{pthread_condattr_destroy} destroys the condition attribute object
|
912 |
|
|
@var{attr}.
|
913 |
|
|
|
914 |
|
|
Both functions do nothing in the LinuxThreads implementation.
|
915 |
|
|
|
916 |
|
|
@code{pthread_condattr_init} and @code{pthread_condattr_destroy} always
|
917 |
|
|
return 0.
|
918 |
|
|
@end deftypefun
|
919 |
|
|
|
920 |
|
|
@node POSIX Semaphores
|
921 |
|
|
@section POSIX Semaphores
|
922 |
|
|
|
923 |
|
|
@vindex SEM_VALUE_MAX
|
924 |
|
|
Semaphores are counters for resources shared between threads. The
|
925 |
|
|
basic operations on semaphores are: increment the counter atomically,
|
926 |
|
|
and wait until the counter is non-null and decrement it atomically.
|
927 |
|
|
|
928 |
|
|
Semaphores have a maximum value past which they cannot be incremented.
|
929 |
|
|
The macro @code{SEM_VALUE_MAX} is defined to be this maximum value. In
|
930 |
|
|
the GNU C library, @code{SEM_VALUE_MAX} is equal to @code{INT_MAX}
|
931 |
|
|
(@pxref{Range of Type}), but it may be much smaller on other systems.
|
932 |
|
|
|
933 |
|
|
The pthreads library implements POSIX 1003.1b semaphores. These should
|
934 |
|
|
not be confused with System V semaphores (@code{ipc}, @code{semctl} and
|
935 |
|
|
@code{semop}).
|
936 |
|
|
@c !!! SysV IPC is not doc'd at all in our manual
|
937 |
|
|
|
938 |
|
|
All the semaphore functions and macros are defined in @file{semaphore.h}.
|
939 |
|
|
|
940 |
|
|
@comment semaphore.h
|
941 |
|
|
@comment POSIX
|
942 |
|
|
@deftypefun int sem_init (sem_t *@var{sem}, int @var{pshared}, unsigned int @var{value})
|
943 |
|
|
@code{sem_init} initializes the semaphore object pointed to by
|
944 |
|
|
@var{sem}. The count associated with the semaphore is set initially to
|
945 |
|
|
@var{value}. The @var{pshared} argument indicates whether the semaphore
|
946 |
|
|
is local to the current process (@var{pshared} is zero) or is to be
|
947 |
|
|
shared between several processes (@var{pshared} is not zero).
|
948 |
|
|
|
949 |
|
|
On success @code{sem_init} returns 0. On failure it returns -1 and sets
|
950 |
|
|
@var{errno} to one of the following values:
|
951 |
|
|
|
952 |
|
|
@table @code
|
953 |
|
|
@item EINVAL
|
954 |
|
|
@var{value} exceeds the maximal counter value @code{SEM_VALUE_MAX}
|
955 |
|
|
|
956 |
|
|
@item ENOSYS
|
957 |
|
|
@var{pshared} is not zero. LinuxThreads currently does not support
|
958 |
|
|
process-shared semaphores. (This will eventually change.)
|
959 |
|
|
@end table
|
960 |
|
|
@end deftypefun
|
961 |
|
|
|
962 |
|
|
@comment semaphore.h
|
963 |
|
|
@comment POSIX
|
964 |
|
|
@deftypefun int sem_destroy (sem_t * @var{sem})
|
965 |
|
|
@code{sem_destroy} destroys a semaphore object, freeing the resources it
|
966 |
|
|
might hold. If any threads are waiting on the semaphore when
|
967 |
|
|
@code{sem_destroy} is called, it fails and sets @var{errno} to
|
968 |
|
|
@code{EBUSY}.
|
969 |
|
|
|
970 |
|
|
In the LinuxThreads implementation, no resources are associated with
|
971 |
|
|
semaphore objects, thus @code{sem_destroy} actually does nothing except
|
972 |
|
|
checking that no thread is waiting on the semaphore. This will change
|
973 |
|
|
when process-shared semaphores are implemented.
|
974 |
|
|
@end deftypefun
|
975 |
|
|
|
976 |
|
|
@comment semaphore.h
|
977 |
|
|
@comment POSIX
|
978 |
|
|
@deftypefun int sem_wait (sem_t * @var{sem})
|
979 |
|
|
@code{sem_wait} suspends the calling thread until the semaphore pointed
|
980 |
|
|
to by @var{sem} has non-zero count. It then atomically decreases the
|
981 |
|
|
semaphore count.
|
982 |
|
|
|
983 |
|
|
@code{sem_wait} is a cancellation point. It always returns 0.
|
984 |
|
|
@end deftypefun
|
985 |
|
|
|
986 |
|
|
@comment semaphore.h
|
987 |
|
|
@comment POSIX
|
988 |
|
|
@deftypefun int sem_trywait (sem_t * @var{sem})
|
989 |
|
|
@code{sem_trywait} is a non-blocking variant of @code{sem_wait}. If the
|
990 |
|
|
semaphore pointed to by @var{sem} has non-zero count, the count is
|
991 |
|
|
atomically decreased and @code{sem_trywait} immediately returns 0. If
|
992 |
|
|
the semaphore count is zero, @code{sem_trywait} immediately returns -1
|
993 |
|
|
and sets errno to @code{EAGAIN}.
|
994 |
|
|
@end deftypefun
|
995 |
|
|
|
996 |
|
|
@comment semaphore.h
|
997 |
|
|
@comment POSIX
|
998 |
|
|
@deftypefun int sem_post (sem_t * @var{sem})
|
999 |
|
|
@code{sem_post} atomically increases the count of the semaphore pointed to
|
1000 |
|
|
by @var{sem}. This function never blocks.
|
1001 |
|
|
|
1002 |
|
|
@c !!! This para appears not to agree with the code.
|
1003 |
|
|
On processors supporting atomic compare-and-swap (Intel 486, Pentium and
|
1004 |
|
|
later, Alpha, PowerPC, MIPS II, Motorola 68k, Ultrasparc), the
|
1005 |
|
|
@code{sem_post} function is can safely be called from signal handlers.
|
1006 |
|
|
This is the only thread synchronization function provided by POSIX
|
1007 |
|
|
threads that is async-signal safe. On the Intel 386 and earlier Sparc
|
1008 |
|
|
chips, the current LinuxThreads implementation of @code{sem_post} is not
|
1009 |
|
|
async-signal safe, because the hardware does not support the required
|
1010 |
|
|
atomic operations.
|
1011 |
|
|
|
1012 |
|
|
@code{sem_post} always succeeds and returns 0, unless the semaphore
|
1013 |
|
|
count would exceed @code{SEM_VALUE_MAX} after being incremented. In
|
1014 |
|
|
that case @code{sem_post} returns -1 and sets @var{errno} to
|
1015 |
|
|
@code{EINVAL}. The semaphore count is left unchanged.
|
1016 |
|
|
@end deftypefun
|
1017 |
|
|
|
1018 |
|
|
@comment semaphore.h
|
1019 |
|
|
@comment POSIX
|
1020 |
|
|
@deftypefun int sem_getvalue (sem_t * @var{sem}, int * @var{sval})
|
1021 |
|
|
@code{sem_getvalue} stores in the location pointed to by @var{sval} the
|
1022 |
|
|
current count of the semaphore @var{sem}. It always returns 0.
|
1023 |
|
|
@end deftypefun
|
1024 |
|
|
|
1025 |
|
|
@node Thread-Specific Data
|
1026 |
|
|
@section Thread-Specific Data
|
1027 |
|
|
|
1028 |
|
|
Programs often need global or static variables that have different
|
1029 |
|
|
values in different threads. Since threads share one memory space, this
|
1030 |
|
|
cannot be achieved with regular variables. Thread-specific data is the
|
1031 |
|
|
POSIX threads answer to this need.
|
1032 |
|
|
|
1033 |
|
|
Each thread possesses a private memory block, the thread-specific data
|
1034 |
|
|
area, or TSD area for short. This area is indexed by TSD keys. The TSD
|
1035 |
|
|
area associates values of type @code{void *} to TSD keys. TSD keys are
|
1036 |
|
|
common to all threads, but the value associated with a given TSD key can
|
1037 |
|
|
be different in each thread.
|
1038 |
|
|
|
1039 |
|
|
For concreteness, the TSD areas can be viewed as arrays of @code{void *}
|
1040 |
|
|
pointers, TSD keys as integer indices into these arrays, and the value
|
1041 |
|
|
of a TSD key as the value of the corresponding array element in the
|
1042 |
|
|
calling thread.
|
1043 |
|
|
|
1044 |
|
|
When a thread is created, its TSD area initially associates @code{NULL}
|
1045 |
|
|
with all keys.
|
1046 |
|
|
|
1047 |
|
|
@comment pthread.h
|
1048 |
|
|
@comment POSIX
|
1049 |
|
|
@deftypefun int pthread_key_create (pthread_key_t *@var{key}, void (*destr_function) (void *))
|
1050 |
|
|
@code{pthread_key_create} allocates a new TSD key. The key is stored in
|
1051 |
|
|
the location pointed to by @var{key}. There is a limit of
|
1052 |
|
|
@code{PTHREAD_KEYS_MAX} on the number of keys allocated at a given
|
1053 |
|
|
time. The value initially associated with the returned key is
|
1054 |
|
|
@code{NULL} in all currently executing threads.
|
1055 |
|
|
|
1056 |
|
|
The @var{destr_function} argument, if not @code{NULL}, specifies a
|
1057 |
|
|
destructor function associated with the key. When a thread terminates
|
1058 |
|
|
via @code{pthread_exit} or by cancellation, @var{destr_function} is
|
1059 |
|
|
called on the value associated with the key in that thread. The
|
1060 |
|
|
@var{destr_function} is not called if a key is deleted with
|
1061 |
|
|
@code{pthread_key_delete} or a value is changed with
|
1062 |
|
|
@code{pthread_setspecific}. The order in which destructor functions are
|
1063 |
|
|
called at thread termination time is unspecified.
|
1064 |
|
|
|
1065 |
|
|
Before the destructor function is called, the @code{NULL} value is
|
1066 |
|
|
associated with the key in the current thread. A destructor function
|
1067 |
|
|
might, however, re-associate non-@code{NULL} values to that key or some
|
1068 |
|
|
other key. To deal with this, if after all the destructors have been
|
1069 |
|
|
called for all non-@code{NULL} values, there are still some
|
1070 |
|
|
non-@code{NULL} values with associated destructors, then the process is
|
1071 |
|
|
repeated. The LinuxThreads implementation stops the process after
|
1072 |
|
|
@code{PTHREAD_DESTRUCTOR_ITERATIONS} iterations, even if some
|
1073 |
|
|
non-@code{NULL} values with associated descriptors remain. Other
|
1074 |
|
|
implementations may loop indefinitely.
|
1075 |
|
|
|
1076 |
|
|
@code{pthread_key_create} returns 0 unless @code{PTHREAD_KEYS_MAX} keys
|
1077 |
|
|
have already been allocated, in which case it fails and returns
|
1078 |
|
|
@code{EAGAIN}.
|
1079 |
|
|
@end deftypefun
|
1080 |
|
|
|
1081 |
|
|
|
1082 |
|
|
@comment pthread.h
|
1083 |
|
|
@comment POSIX
|
1084 |
|
|
@deftypefun int pthread_key_delete (pthread_key_t @var{key})
|
1085 |
|
|
@code{pthread_key_delete} deallocates a TSD key. It does not check
|
1086 |
|
|
whether non-@code{NULL} values are associated with that key in the
|
1087 |
|
|
currently executing threads, nor call the destructor function associated
|
1088 |
|
|
with the key.
|
1089 |
|
|
|
1090 |
|
|
If there is no such key @var{key}, it returns @code{EINVAL}. Otherwise
|
1091 |
|
|
it returns 0.
|
1092 |
|
|
@end deftypefun
|
1093 |
|
|
|
1094 |
|
|
@comment pthread.h
|
1095 |
|
|
@comment POSIX
|
1096 |
|
|
@deftypefun int pthread_setspecific (pthread_key_t @var{key}, const void *@var{pointer})
|
1097 |
|
|
@code{pthread_setspecific} changes the value associated with @var{key}
|
1098 |
|
|
in the calling thread, storing the given @var{pointer} instead.
|
1099 |
|
|
|
1100 |
|
|
If there is no such key @var{key}, it returns @code{EINVAL}. Otherwise
|
1101 |
|
|
it returns 0.
|
1102 |
|
|
@end deftypefun
|
1103 |
|
|
|
1104 |
|
|
@comment pthread.h
|
1105 |
|
|
@comment POSIX
|
1106 |
|
|
@deftypefun {void *} pthread_getspecific (pthread_key_t @var{key})
|
1107 |
|
|
@code{pthread_getspecific} returns the value currently associated with
|
1108 |
|
|
@var{key} in the calling thread.
|
1109 |
|
|
|
1110 |
|
|
If there is no such key @var{key}, it returns @code{NULL}.
|
1111 |
|
|
@end deftypefun
|
1112 |
|
|
|
1113 |
|
|
The following code fragment allocates a thread-specific array of 100
|
1114 |
|
|
characters, with automatic reclaimation at thread exit:
|
1115 |
|
|
|
1116 |
|
|
@smallexample
|
1117 |
|
|
/* Key for the thread-specific buffer */
|
1118 |
|
|
static pthread_key_t buffer_key;
|
1119 |
|
|
|
1120 |
|
|
/* Once-only initialisation of the key */
|
1121 |
|
|
static pthread_once_t buffer_key_once = PTHREAD_ONCE_INIT;
|
1122 |
|
|
|
1123 |
|
|
/* Allocate the thread-specific buffer */
|
1124 |
|
|
void buffer_alloc(void)
|
1125 |
|
|
@{
|
1126 |
|
|
pthread_once(&buffer_key_once, buffer_key_alloc);
|
1127 |
|
|
pthread_setspecific(buffer_key, malloc(100));
|
1128 |
|
|
@}
|
1129 |
|
|
|
1130 |
|
|
/* Return the thread-specific buffer */
|
1131 |
|
|
char * get_buffer(void)
|
1132 |
|
|
@{
|
1133 |
|
|
return (char *) pthread_getspecific(buffer_key);
|
1134 |
|
|
@}
|
1135 |
|
|
|
1136 |
|
|
/* Allocate the key */
|
1137 |
|
|
static void buffer_key_alloc()
|
1138 |
|
|
@{
|
1139 |
|
|
pthread_key_create(&buffer_key, buffer_destroy);
|
1140 |
|
|
@}
|
1141 |
|
|
|
1142 |
|
|
/* Free the thread-specific buffer */
|
1143 |
|
|
static void buffer_destroy(void * buf)
|
1144 |
|
|
@{
|
1145 |
|
|
free(buf);
|
1146 |
|
|
@}
|
1147 |
|
|
@end smallexample
|
1148 |
|
|
|
1149 |
|
|
@node Threads and Signal Handling
|
1150 |
|
|
@section Threads and Signal Handling
|
1151 |
|
|
|
1152 |
|
|
@comment pthread.h
|
1153 |
|
|
@comment POSIX
|
1154 |
|
|
@deftypefun int pthread_sigmask (int @var{how}, const sigset_t *@var{newmask}, sigset_t *@var{oldmask})
|
1155 |
|
|
@code{pthread_sigmask} changes the signal mask for the calling thread as
|
1156 |
|
|
described by the @var{how} and @var{newmask} arguments. If @var{oldmask}
|
1157 |
|
|
is not @code{NULL}, the previous signal mask is stored in the location
|
1158 |
|
|
pointed to by @var{oldmask}.
|
1159 |
|
|
|
1160 |
|
|
The meaning of the @var{how} and @var{newmask} arguments is the same as
|
1161 |
|
|
for @code{sigprocmask}. If @var{how} is @code{SIG_SETMASK}, the signal
|
1162 |
|
|
mask is set to @var{newmask}. If @var{how} is @code{SIG_BLOCK}, the
|
1163 |
|
|
signals specified to @var{newmask} are added to the current signal mask.
|
1164 |
|
|
If @var{how} is @code{SIG_UNBLOCK}, the signals specified to
|
1165 |
|
|
@var{newmask} are removed from the current signal mask.
|
1166 |
|
|
|
1167 |
|
|
Recall that signal masks are set on a per-thread basis, but signal
|
1168 |
|
|
actions and signal handlers, as set with @code{sigaction}, are shared
|
1169 |
|
|
between all threads.
|
1170 |
|
|
|
1171 |
|
|
The @code{pthread_sigmask} function returns 0 on success, and one of the
|
1172 |
|
|
following error codes on error:
|
1173 |
|
|
@table @code
|
1174 |
|
|
@item EINVAL
|
1175 |
|
|
@var{how} is not one of @code{SIG_SETMASK}, @code{SIG_BLOCK}, or @code{SIG_UNBLOCK}
|
1176 |
|
|
|
1177 |
|
|
@item EFAULT
|
1178 |
|
|
@var{newmask} or @var{oldmask} point to invalid addresses
|
1179 |
|
|
@end table
|
1180 |
|
|
@end deftypefun
|
1181 |
|
|
|
1182 |
|
|
@comment pthread.h
|
1183 |
|
|
@comment POSIX
|
1184 |
|
|
@deftypefun int pthread_kill (pthread_t @var{thread}, int @var{signo})
|
1185 |
|
|
@code{pthread_kill} sends signal number @var{signo} to the thread
|
1186 |
|
|
@var{thread}. The signal is delivered and handled as described in
|
1187 |
|
|
@ref{Signal Handling}.
|
1188 |
|
|
|
1189 |
|
|
@code{pthread_kill} returns 0 on success, one of the following error codes
|
1190 |
|
|
on error:
|
1191 |
|
|
@table @code
|
1192 |
|
|
@item EINVAL
|
1193 |
|
|
@var{signo} is not a valid signal number
|
1194 |
|
|
|
1195 |
|
|
@item ESRCH
|
1196 |
|
|
The thread @var{thread} does not exist (e.g. it has already terminated)
|
1197 |
|
|
@end table
|
1198 |
|
|
@end deftypefun
|
1199 |
|
|
|
1200 |
|
|
@comment pthread.h
|
1201 |
|
|
@comment POSIX
|
1202 |
|
|
@deftypefun int sigwait (const sigset_t *@var{set}, int *@var{sig})
|
1203 |
|
|
@code{sigwait} suspends the calling thread until one of the signals in
|
1204 |
|
|
@var{set} is delivered to the calling thread. It then stores the number
|
1205 |
|
|
of the signal received in the location pointed to by @var{sig} and
|
1206 |
|
|
returns. The signals in @var{set} must be blocked and not ignored on
|
1207 |
|
|
entrance to @code{sigwait}. If the delivered signal has a signal handler
|
1208 |
|
|
function attached, that function is @emph{not} called.
|
1209 |
|
|
|
1210 |
|
|
@code{sigwait} is a cancellation point. It always returns 0.
|
1211 |
|
|
@end deftypefun
|
1212 |
|
|
|
1213 |
|
|
For @code{sigwait} to work reliably, the signals being waited for must be
|
1214 |
|
|
blocked in all threads, not only in the calling thread, since
|
1215 |
|
|
otherwise the POSIX semantics for signal delivery do not guarantee
|
1216 |
|
|
that it's the thread doing the @code{sigwait} that will receive the signal.
|
1217 |
|
|
The best way to achieve this is block those signals before any threads
|
1218 |
|
|
are created, and never unblock them in the program other than by
|
1219 |
|
|
calling @code{sigwait}.
|
1220 |
|
|
|
1221 |
|
|
Signal handling in LinuxThreads departs significantly from the POSIX
|
1222 |
|
|
standard. According to the standard, ``asynchronous'' (external) signals
|
1223 |
|
|
are addressed to the whole process (the collection of all threads),
|
1224 |
|
|
which then delivers them to one particular thread. The thread that
|
1225 |
|
|
actually receives the signal is any thread that does not currently block
|
1226 |
|
|
the signal.
|
1227 |
|
|
|
1228 |
|
|
In LinuxThreads, each thread is actually a kernel process with its own
|
1229 |
|
|
PID, so external signals are always directed to one particular thread.
|
1230 |
|
|
If, for instance, another thread is blocked in @code{sigwait} on that
|
1231 |
|
|
signal, it will not be restarted.
|
1232 |
|
|
|
1233 |
|
|
The LinuxThreads implementation of @code{sigwait} installs dummy signal
|
1234 |
|
|
handlers for the signals in @var{set} for the duration of the
|
1235 |
|
|
wait. Since signal handlers are shared between all threads, other
|
1236 |
|
|
threads must not attach their own signal handlers to these signals, or
|
1237 |
|
|
alternatively they should all block these signals (which is recommended
|
1238 |
|
|
anyway).
|
1239 |
|
|
|
1240 |
|
|
@node Miscellaneous Thread Functions
|
1241 |
|
|
@section Miscellaneous Thread Functions
|
1242 |
|
|
|
1243 |
|
|
@comment pthread.h
|
1244 |
|
|
@comment POSIX
|
1245 |
|
|
@deftypefun {pthread_t} pthread_self (@var{void})
|
1246 |
|
|
@code{pthread_self} returns the thread identifier for the calling thread.
|
1247 |
|
|
@end deftypefun
|
1248 |
|
|
|
1249 |
|
|
@comment pthread.h
|
1250 |
|
|
@comment POSIX
|
1251 |
|
|
@deftypefun int pthread_equal (pthread_t thread1, pthread_t thread2)
|
1252 |
|
|
@code{pthread_equal} determines if two thread identifiers refer to the same
|
1253 |
|
|
thread.
|
1254 |
|
|
|
1255 |
|
|
A non-zero value is returned if @var{thread1} and @var{thread2} refer to
|
1256 |
|
|
the same thread. Otherwise, 0 is returned.
|
1257 |
|
|
@end deftypefun
|
1258 |
|
|
|
1259 |
|
|
@comment pthread.h
|
1260 |
|
|
@comment POSIX
|
1261 |
|
|
@deftypefun int pthread_detach (pthread_t @var{th})
|
1262 |
|
|
@code{pthread_detach} puts the thread @var{th} in the detached
|
1263 |
|
|
state. This guarantees that the memory resources consumed by @var{th}
|
1264 |
|
|
will be freed immediately when @var{th} terminates. However, this
|
1265 |
|
|
prevents other threads from synchronizing on the termination of @var{th}
|
1266 |
|
|
using @code{pthread_join}.
|
1267 |
|
|
|
1268 |
|
|
A thread can be created initially in the detached state, using the
|
1269 |
|
|
@code{detachstate} attribute to @code{pthread_create}. In contrast,
|
1270 |
|
|
@code{pthread_detach} applies to threads created in the joinable state,
|
1271 |
|
|
and which need to be put in the detached state later.
|
1272 |
|
|
|
1273 |
|
|
After @code{pthread_detach} completes, subsequent attempts to perform
|
1274 |
|
|
@code{pthread_join} on @var{th} will fail. If another thread is already
|
1275 |
|
|
joining the thread @var{th} at the time @code{pthread_detach} is called,
|
1276 |
|
|
@code{pthread_detach} does nothing and leaves @var{th} in the joinable
|
1277 |
|
|
state.
|
1278 |
|
|
|
1279 |
|
|
On success, 0 is returned. On error, one of the following codes is
|
1280 |
|
|
returned:
|
1281 |
|
|
@table @code
|
1282 |
|
|
@item ESRCH
|
1283 |
|
|
No thread could be found corresponding to that specified by @var{th}
|
1284 |
|
|
@item EINVAL
|
1285 |
|
|
The thread @var{th} is already in the detached state
|
1286 |
|
|
@end table
|
1287 |
|
|
@end deftypefun
|
1288 |
|
|
|
1289 |
|
|
@comment pthread.h
|
1290 |
|
|
@comment POSIX
|
1291 |
|
|
@deftypefun int pthread_atfork (void (*@var{prepare})(void), void (*@var{parent})(void), void (*@var{child})(void))
|
1292 |
|
|
|
1293 |
|
|
@code{pthread_atfork} registers handler functions to be called just
|
1294 |
|
|
before and just after a new process is created with @code{fork}. The
|
1295 |
|
|
@var{prepare} handler will be called from the parent process, just
|
1296 |
|
|
before the new process is created. The @var{parent} handler will be
|
1297 |
|
|
called from the parent process, just before @code{fork} returns. The
|
1298 |
|
|
@var{child} handler will be called from the child process, just before
|
1299 |
|
|
@code{fork} returns.
|
1300 |
|
|
|
1301 |
|
|
@code{pthread_atfork} returns 0 on success and a non-zero error code on
|
1302 |
|
|
error.
|
1303 |
|
|
|
1304 |
|
|
One or more of the three handlers @var{prepare}, @var{parent} and
|
1305 |
|
|
@var{child} can be given as @code{NULL}, meaning that no handler needs
|
1306 |
|
|
to be called at the corresponding point.
|
1307 |
|
|
|
1308 |
|
|
@code{pthread_atfork} can be called several times to install several
|
1309 |
|
|
sets of handlers. At @code{fork} time, the @var{prepare} handlers are
|
1310 |
|
|
called in LIFO order (last added with @code{pthread_atfork}, first
|
1311 |
|
|
called before @code{fork}), while the @var{parent} and @var{child}
|
1312 |
|
|
handlers are called in FIFO order (first added, first called).
|
1313 |
|
|
|
1314 |
|
|
If there is insufficient memory available to register the handlers,
|
1315 |
|
|
@code{pthread_atfork} fails and returns @code{ENOMEM}. Otherwise it
|
1316 |
|
|
returns 0.
|
1317 |
|
|
@end deftypefun
|
1318 |
|
|
|
1319 |
|
|
To understand the purpose of @code{pthread_atfork}, recall that
|
1320 |
|
|
@code{fork} duplicates the whole memory space, including mutexes in
|
1321 |
|
|
their current locking state, but only the calling thread: other threads
|
1322 |
|
|
are not running in the child process. Thus, if a mutex is locked by a
|
1323 |
|
|
thread other than the thread calling @code{fork}, that mutex will remain
|
1324 |
|
|
locked forever in the child process, possibly blocking the execution of
|
1325 |
|
|
the child process. To avoid this, install handlers with
|
1326 |
|
|
@code{pthread_atfork} as follows: the @var{prepare} handler locks the
|
1327 |
|
|
global mutexes (in locking order), and the @var{parent} and @var{child}
|
1328 |
|
|
handlers unlock them (in reverse order). Alternatively, @var{prepare}
|
1329 |
|
|
and @var{parent} can be set to @code{NULL} and @var{child} to a function
|
1330 |
|
|
that calls @code{pthread_mutex_init} on the global mutexes.
|
1331 |
|
|
|
1332 |
|
|
@comment pthread.h
|
1333 |
|
|
@comment GNU
|
1334 |
|
|
@deftypefun void pthread_kill_other_threads_np (@var{void})
|
1335 |
|
|
@code{pthread_kill_other_threads_np} is a non-portable LinuxThreads extension.
|
1336 |
|
|
It causes all threads in the program to terminate immediately, except
|
1337 |
|
|
the calling thread which proceeds normally. It is intended to be
|
1338 |
|
|
called just before a thread calls one of the @code{exec} functions,
|
1339 |
|
|
e.g. @code{execve}.
|
1340 |
|
|
|
1341 |
|
|
Termination of the other threads is not performed through
|
1342 |
|
|
@code{pthread_cancel} and completely bypasses the cancellation
|
1343 |
|
|
mechanism. Hence, the current settings for cancellation state and
|
1344 |
|
|
cancellation type are ignored, and the cleanup handlers are not
|
1345 |
|
|
executed in the terminated threads.
|
1346 |
|
|
|
1347 |
|
|
According to POSIX 1003.1c, a successful @code{exec*} in one of the
|
1348 |
|
|
threads should automatically terminate all other threads in the program.
|
1349 |
|
|
This behavior is not yet implemented in LinuxThreads. Calling
|
1350 |
|
|
@code{pthread_kill_other_threads_np} before @code{exec*} achieves much
|
1351 |
|
|
of the same behavior, except that if @code{exec*} ultimately fails, then
|
1352 |
|
|
all other threads are already killed.
|
1353 |
|
|
@end deftypefun
|
1354 |
|
|
|
1355 |
|
|
@comment pthread.h
|
1356 |
|
|
@comment POSIX
|
1357 |
|
|
@deftypefun int pthread_once (pthread_once_t *once_@var{control}, void (*@var{init_routine}) (void))
|
1358 |
|
|
|
1359 |
|
|
The purpose of @code{pthread_once} is to ensure that a piece of
|
1360 |
|
|
initialization code is executed at most once. The @var{once_control}
|
1361 |
|
|
argument points to a static or extern variable statically initialized
|
1362 |
|
|
to @code{PTHREAD_ONCE_INIT}.
|
1363 |
|
|
|
1364 |
|
|
The first time @code{pthread_once} is called with a given
|
1365 |
|
|
@var{once_control} argument, it calls @var{init_routine} with no
|
1366 |
|
|
argument and changes the value of the @var{once_control} variable to
|
1367 |
|
|
record that initialization has been performed. Subsequent calls to
|
1368 |
|
|
@code{pthread_once} with the same @code{once_control} argument do
|
1369 |
|
|
nothing.
|
1370 |
|
|
|
1371 |
|
|
@code{pthread_once} always returns 0.
|
1372 |
|
|
@end deftypefun
|
1373 |
|
|
|
1374 |
|
|
@comment pthread.h
|
1375 |
|
|
@comment POSIX
|
1376 |
|
|
@deftypefun int pthread_setschedparam (pthread_t target_@var{thread}, int @var{policy}, const struct sched_param *@var{param})
|
1377 |
|
|
|
1378 |
|
|
@code{pthread_setschedparam} sets the scheduling parameters for the
|
1379 |
|
|
thread @var{target_thread} as indicated by @var{policy} and
|
1380 |
|
|
@var{param}. @var{policy} can be either @code{SCHED_OTHER} (regular,
|
1381 |
|
|
non-realtime scheduling), @code{SCHED_RR} (realtime, round-robin) or
|
1382 |
|
|
@code{SCHED_FIFO} (realtime, first-in first-out). @var{param} specifies
|
1383 |
|
|
the scheduling priority for the two realtime policies. See
|
1384 |
|
|
@code{sched_setpolicy} for more information on scheduling policies.
|
1385 |
|
|
|
1386 |
|
|
The realtime scheduling policies @code{SCHED_RR} and @code{SCHED_FIFO}
|
1387 |
|
|
are available only to processes with superuser privileges.
|
1388 |
|
|
|
1389 |
|
|
On success, @code{pthread_setschedparam} returns 0. On error it returns
|
1390 |
|
|
one of the following codes:
|
1391 |
|
|
@table @code
|
1392 |
|
|
@item EINVAL
|
1393 |
|
|
@var{policy} is not one of @code{SCHED_OTHER}, @code{SCHED_RR},
|
1394 |
|
|
@code{SCHED_FIFO}, or the priority value specified by @var{param} is not
|
1395 |
|
|
valid for the specified policy
|
1396 |
|
|
|
1397 |
|
|
@item EPERM
|
1398 |
|
|
Realtime scheduling was requested but the calling process does not have
|
1399 |
|
|
sufficient privileges.
|
1400 |
|
|
|
1401 |
|
|
@item ESRCH
|
1402 |
|
|
The @var{target_thread} is invalid or has already terminated
|
1403 |
|
|
|
1404 |
|
|
@item EFAULT
|
1405 |
|
|
@var{param} points outside the process memory space
|
1406 |
|
|
@end table
|
1407 |
|
|
@end deftypefun
|
1408 |
|
|
|
1409 |
|
|
@comment pthread.h
|
1410 |
|
|
@comment POSIX
|
1411 |
|
|
@deftypefun int pthread_getschedparam (pthread_t target_@var{thread}, int *@var{policy}, struct sched_param *@var{param})
|
1412 |
|
|
|
1413 |
|
|
@code{pthread_getschedparam} retrieves the scheduling policy and
|
1414 |
|
|
scheduling parameters for the thread @var{target_thread} and stores them
|
1415 |
|
|
in the locations pointed to by @var{policy} and @var{param},
|
1416 |
|
|
respectively.
|
1417 |
|
|
|
1418 |
|
|
@code{pthread_getschedparam} returns 0 on success, or one of the
|
1419 |
|
|
following error codes on failure:
|
1420 |
|
|
@table @code
|
1421 |
|
|
@item ESRCH
|
1422 |
|
|
The @var{target_thread} is invalid or has already terminated.
|
1423 |
|
|
|
1424 |
|
|
@item EFAULT
|
1425 |
|
|
@var{policy} or @var{param} point outside the process memory space.
|
1426 |
|
|
|
1427 |
|
|
@end table
|
1428 |
|
|
@end deftypefun
|