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