1PTHREAD_ATTR_DESTROY(3P) POSIX Programmer's Manual PTHREAD_ATTR_DESTROY(3P)
2
6 This manual page is part of the POSIX Programmer's Manual. The Linux
7 implementation of this interface may differ (consult the corresponding
8 Linux manual page for details of Linux behavior), or the interface may
9 not be implemented on Linux.
10
12 pthread_attr_destroy, pthread_attr_init — destroy and initialize the
13 thread attributes object
14
16 #include <pthread.h>
17 int pthread_attr_destroy(pthread_attr_t *attr);
19 int pthread_attr_init(pthread_attr_t *attr);
20
22 The pthread_attr_destroy() function shall destroy a thread attributes
23 object. An implementation may cause pthread_attr_destroy() to set attr
24 to an implementation-defined invalid value. A destroyed attr attributes
25 object can be reinitialized using pthread_attr_init(); the results of
26 otherwise referencing the object after it has been destroyed are unde‐
27 fined.
28 The pthread_attr_init() function shall initialize a thread attributes
30 object attr with the default value for all of the individual attributes
31 used by a given implementation.
32 The resulting attributes object (possibly modified by setting individ‐
34 ual attribute values) when used by pthread_create() defines the
35 attributes of the thread created. A single attributes object can be
36 used in multiple simultaneous calls to pthread_create(). Results are
37 undefined if pthread_attr_init() is called specifying an already ini‐
38 tialized attr attributes object.
39 The behavior is undefined if the value specified by the attr argument
41 to pthread_attr_destroy() does not refer to an initialized thread
42 attributes object.
43
45 Upon successful completion, pthread_attr_destroy() and
46 pthread_attr_init() shall return a value of 0; otherwise, an error num‐
47 ber shall be returned to indicate the error.
48
50 The pthread_attr_init() function shall fail if:
51 ENOMEM Insufficient memory exists to initialize the thread attributes
53 object.
54 These functions shall not return an error code of [EINTR].
56 The following sections are informative.
58
60 None.
61
63 None.
64
66 Attributes objects are provided for threads, mutexes, and condition
67 variables as a mechanism to support probable future standardization in
68 these areas without requiring that the function itself be changed.
69 Attributes objects provide clean isolation of the configurable aspects
71 of threads. For example, ``stack size'' is an important attribute of a
72 thread, but it cannot be expressed portably. When porting a threaded
73 program, stack sizes often need to be adjusted. The use of attributes
74 objects can help by allowing the changes to be isolated in a single
75 place, rather than being spread across every instance of thread cre‐
76 ation.
77 Attributes objects can be used to set up ``classes' of threads with
79 similar attributes; for example, ``threads with large stacks and high
80 priority'' or ``threads with minimal stacks''. These classes can be
81 defined in a single place and then referenced wherever threads need to
82 be created. Changes to ``class'' decisions become straightforward, and
83 detailed analysis of each pthread_create() call is not required.
84 The attributes objects are defined as opaque types as an aid to exten‐
86 sibility. If these objects had been specified as structures, adding new
87 attributes would force recompilation of all multi-threaded programs
88 when the attributes objects are extended; this might not be possible if
89 different program components were supplied by different vendors.
90 Additionally, opaque attributes objects present opportunities for
92 improving performance. Argument validity can be checked once when
93 attributes are set, rather than each time a thread is created. Imple‐
94 mentations often need to cache kernel objects that are expensive to
95 create. Opaque attributes objects provide an efficient mechanism to
96 detect when cached objects become invalid due to attribute changes.
97 Since assignment is not necessarily defined on a given opaque type,
99 implementation-defined default values cannot be defined in a portable
100 way. The solution to this problem is to allow attributes objects to be
101 initialized dynamically by attributes object initialization functions,
102 so that default values can be supplied automatically by the implementa‐
103 tion.
104 The following proposal was provided as a suggested alternative to the
106 supplied attributes:
107 1. Maintain the style of passing a parameter formed by the bitwise-
109 inclusive OR of flags to the initialization routines (pthread_cre‐
110 ate(), pthread_mutex_init(), pthread_cond_init()). The parameter
111 containing the flags should be an opaque type for extensibility. If
112 no flags are set in the parameter, then the objects are created
113 with default characteristics. An implementation may specify imple‐
114 mentation-defined flag values and associated behavior.
115 2. If further specialization of mutexes and condition variables is
117 necessary, implementations may specify additional procedures that
118 operate on the pthread_mutex_t and pthread_cond_t objects (instead
119 of on attributes objects).
120 The difficulties with this solution are:
122 1. A bitmask is not opaque if bits have to be set into bitvector
124 attributes objects using explicitly-coded bitwise-inclusive OR
125 operations. If the set of options exceeds an int, application pro‐
126 grammers need to know the location of each bit. If bits are set or
127 read by encapsulation (that is, get and set functions), then the
128 bitmask is merely an implementation of attributes objects as cur‐
129 rently defined and should not be exposed to the programmer.
130 2. Many attributes are not Boolean or very small integral values. For
132 example, scheduling policy may be placed in 3-bit or 4-bit, but
133 priority requires 5-bit or more, thereby taking up at least 8 bits
134 out of a possible 16 bits on machines with 16-bit integers. Because
135 of this, the bitmask can only reasonably control whether particular
136 attributes are set or not, and it cannot serve as the repository of
137 the value itself. The value needs to be specified as a function
138 parameter (which is non-extensible), or by setting a structure
139 field (which is non-opaque), or by get and set functions (making
140 the bitmask a redundant addition to the attributes objects).
141 Stack size is defined as an optional attribute because the very notion
143 of a stack is inherently machine-dependent. Some implementations may
144 not be able to change the size of the stack, for example, and others
145 may not need to because stack pages may be discontiguous and can be
146 allocated and released on demand.
147 The attribute mechanism has been designed in large measure for extensi‐
149 bility. Future extensions to the attribute mechanism or to any
150 attributes object defined in this volume of POSIX.1‐2017 has to be done
151 with care so as not to affect binary-compatibility.
152 Attributes objects, even if allocated by means of dynamic allocation
154 functions such as malloc(), may have their size fixed at compile time.
155 This means, for example, a pthread_create() in an implementation with
156 extensions to pthread_attr_t cannot look beyond the area that the
157 binary application assumes is valid. This suggests that implementations
158 should maintain a size field in the attributes object, as well as pos‐
159 sibly version information, if extensions in different directions (pos‐
160 sibly by different vendors) are to be accommodated.
161 If an implementation detects that the value specified by the attr argu‐
163 ment to pthread_attr_destroy() does not refer to an initialized thread
164 attributes object, it is recommended that the function should fail and
165 report an [EINVAL] error.
166 If an implementation detects that the value specified by the attr argu‐
168 ment to pthread_attr_init() refers to an already initialized thread
169 attributes object, it is recommended that the function should fail and
170 report an [EBUSY] error.
171
173 None.
174
176 pthread_attr_getstacksize(), pthread_attr_getdetachstate(),
177 pthread_create()
178 The Base Definitions volume of POSIX.1‐2017, <pthread.h>
180
182 Portions of this text are reprinted and reproduced in electronic form
183 from IEEE Std 1003.1-2017, Standard for Information Technology -- Por‐
184 table Operating System Interface (POSIX), The Open Group Base Specifi‐
185 cations Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of
186 Electrical and Electronics Engineers, Inc and The Open Group. In the
187 event of any discrepancy between this version and the original IEEE and
188 The Open Group Standard, the original IEEE and The Open Group Standard
189 is the referee document. The original Standard can be obtained online
190 at http://www.opengroup.org/unix/online.html .
191 Any typographical or formatting errors that appear in this page are
193 most likely to have been introduced during the conversion of the source
194 files to man page format. To report such errors, see https://www.ker‐
195 nel.org/doc/man-pages/reporting_bugs.html .
196IEEE/The Open Group 2017 PTHREAD_ATTR_DESTROY(3P)