OpenCores
URL https://opencores.org/ocsvn/or1k/or1k/trunk

Subversion Repositories or1k

[/] [or1k/] [trunk/] [linux/] [uClibc/] [libpthread/] [linuxthreads/] [linuxthreads.texi] - Blame information for rev 1765

Details | Compare with Previous | View Log

Line No. Rev Author Line
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

powered by: WebSVN 2.1.0

© copyright 1999-2025 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.