summaryrefslogtreecommitdiff
path: root/manual/threads.texi
blob: a23ac261ef4695afe1b4e939b275fc2fb7ca0595 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
@node POSIX Threads
@c @node POSIX Threads, , Cryptographic Functions, Top
@chapter POSIX Threads
@c %MENU% POSIX Threads
@cindex pthreads

This chapter describes the @glibcadj{} POSIX Thread implementation.

@menu
* Thread-specific Data::          Support for creating and
				  managing thread-specific data
* Non-POSIX Extensions::          Additional functions to extend
				  POSIX Thread functionality
@end menu

@node Thread-specific Data
@section Thread-specific Data

The @glibcadj{} implements functions to allow users to create and manage
data specific to a thread.  Such data may be destroyed at thread exit,
if a destructor is provided.  The following functions are defined:

@table @code

@item int pthread_key_create (pthread_key_t *@var{key}, void (*@var{destructor})(void*))
Create a thread-specific data key for the calling thread, referenced by
@var{key}.

Objects declared with the C++11 @code{thread_local} keyword are destroyed
before thread-specific data, so they should not be used in thread-specific
data destructors or even as members of the thread-specific data, since the
latter is passed as an argument to the destructor function.

@item int pthread_key_delete (pthread_key_t @var{key})
Destroy the thread-specific data @var{key} in the calling thread.  The
destructor for the thread-specific data is not called during destruction, nor
is it called during thread exit.

@item void *pthread_getspecific (pthread_key_t @var{key})
Return the thread-specific data associated with @var{key} in the calling
thread.

@item int pthread_setspecific (pthread_key_t @var{key}, const void *@var{value})
Associate the thread-specific @var{value} with @var{key} in the calling thread.

@end table

@node Non-POSIX Extensions
@section Non-POSIX Extensions

In addition to implementing the POSIX API for threads, @theglibc{} provides
additional functions and interfaces to provide functionality not specified in
the standard.

@menu
* Default Thread Attributes::             Setting default attributes for
					  threads in a process.
@end menu

@node Default Thread Attributes
@subsection Setting Process-wide defaults for thread attributes

@Theglibc{} provides non-standard API functions to set and get the default
attributes used in the creation of threads in a process.

@deftypefun int pthread_getattr_default_np (pthread_attr_t *@var{attr})
Get the default attribute values and set @var{attr} to match.  This
function returns @math{0} on success and a non-zero error code on
failure.
@end deftypefun

@deftypefun int pthread_getattr_default_np (pthread_attr_t *@var{attr})
Set the default attribute values to match the values in @var{attr}.  The
function returns @math{0} on success and a non-zero error code on failure.
The following error codes are defined for this function:

@table @code
@item EINVAL
At least one of the values in @var{attr} does not qualify as valid for the
attributes or the stack address is set in the attribute.
@item ENOMEM
The system does not have sufficient memory.
@end table
@end deftypefun