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
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
42 Upon successful completion, pthread_attr_destroy() and
43 pthread_attr_init() shall return a value of 0; otherwise, an error num‐
44 ber shall be returned to indicate the error.
45
47 The pthread_attr_init() function shall fail if:
48 ENOMEM Insufficient memory exists to initialize the thread attributes
50 object.
51 These functions shall not return an error code of [EINTR].
54 The following sections are informative.
56
58 None.
59
61 None.
62
64 Attributes objects are provided for threads, mutexes, and condition
65 variables as a mechanism to support probable future standardization in
66 these areas without requiring that the function itself be changed.
67 Attributes objects provide clean isolation of the configurable aspects
69 of threads. For example, "stack size" is an important attribute of a
70 thread, but it cannot be expressed portably. When porting a threaded
71 program, stack sizes often need to be adjusted. The use of attributes
72 objects can help by allowing the changes to be isolated in a single
73 place, rather than being spread across every instance of thread cre‐
74 ation.
75 Attributes objects can be used to set up "classes' of threads with sim‐
77 ilar attributes; for example, "threads with large stacks and high pri‐
78 ority" or "threads with minimal stacks". These classes can be defined
79 in a single place and then referenced wherever threads need to be cre‐
80 ated. Changes to "class" decisions become straightforward, and detailed
81 analysis of each pthread_create() call is not required.
82 The attributes objects are defined as opaque types as an aid to exten‐
84 sibility. If these objects had been specified as structures, adding
85 new attributes would force recompilation of all multi-threaded programs
86 when the attributes objects are extended; this might not be possible if
87 different program components were supplied by different vendors.
88 Additionally, opaque attributes objects present opportunities for
90 improving performance. Argument validity can be checked once when
91 attributes are set, rather than each time a thread is created. Imple‐
92 mentations often need to cache kernel objects that are expensive to
93 create. Opaque attributes objects provide an efficient mechanism to
94 detect when cached objects become invalid due to attribute changes.
95 Since assignment is not necessarily defined on a given opaque type,
97 implementation-defined default values cannot be defined in a portable
98 way. The solution to this problem is to allow attributes objects to be
99 initialized dynamically by attributes object initialization functions,
100 so that default values can be supplied automatically by the implementa‐
101 tion.
102 The following proposal was provided as a suggested alternative to the
104 supplied attributes:
105 1. Maintain the style of passing a parameter formed by the bitwise-
107 inclusive OR of flags to the initialization routines ( pthread_cre‐
108 ate(), pthread_mutex_init(), pthread_cond_init()). The parameter
109 containing the flags should be an opaque type for extensibility. If
110 no flags are set in the parameter, then the objects are created
111 with default characteristics. An implementation may specify imple‐
112 mentation-defined flag values and associated behavior.
113 2. If further specialization of mutexes and condition variables is
115 necessary, implementations may specify additional procedures that
116 operate on the pthread_mutex_t and pthread_cond_t objects (instead
117 of on attributes objects).
118 The difficulties with this solution are:
120 1. A bitmask is not opaque if bits have to be set into bitvector
122 attributes objects using explicitly-coded bitwise-inclusive OR
123 operations. If the set of options exceeds an int, application pro‐
124 grammers need to know the location of each bit. If bits are set or
125 read by encapsulation (that is, get and set functions), then the
126 bitmask is merely an implementation of attributes objects as cur‐
127 rently defined and should not be exposed to the programmer.
128 2. Many attributes are not Boolean or very small integral values. For
130 example, scheduling policy may be placed in 3-bit or 4-bit, but
131 priority requires 5-bit or more, thereby taking up at least 8 bits
132 out of a possible 16 bits on machines with 16-bit integers.
133 Because of this, the bitmask can only reasonably control whether
134 particular attributes are set or not, and it cannot serve as the
135 repository of the value itself. The value needs to be specified as
136 a function parameter (which is non-extensible), or by setting a
137 structure field (which is non-opaque), or by get and set functions
138 (making the bitmask a redundant addition to the attributes
139 objects).
140 Stack size is defined as an optional attribute because the very notion
142 of a stack is inherently machine-dependent. Some implementations may
143 not be able to change the size of the stack, for example, and others
144 may not need to because stack pages may be discontiguous and can be
145 allocated and released on demand.
146 The attribute mechanism has been designed in large measure for extensi‐
148 bility. Future extensions to the attribute mechanism or to any
149 attributes object defined in this volume of IEEE Std 1003.1-2001 has to
150 be done with care so as not to affect binary-compatibility.
151 Attributes objects, even if allocated by means of dynamic allocation
153 functions such as malloc(), may have their size fixed at compile time.
154 This means, for example, a pthread_create() in an implementation with
155 extensions to pthread_attr_t cannot look beyond the area that the
156 binary application assumes is valid. This suggests that implementa‐
157 tions should maintain a size field in the attributes object, as well as
158 possibly version information, if extensions in different directions
159 (possibly by different vendors) are to be accommodated.
160
162 None.
163
165 pthread_attr_getstackaddr(), pthread_attr_getstacksize(),
166 pthread_attr_getdetachstate(), pthread_create(), the Base Definitions
167 volume of IEEE Std 1003.1-2001, <pthread.h>
168
170 Portions of this text are reprinted and reproduced in electronic form
171 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
172 -- Portable Operating System Interface (POSIX), The Open Group Base
173 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
174 Electrical and Electronics Engineers, Inc and The Open Group. In the
175 event of any discrepancy between this version and the original IEEE and
176 The Open Group Standard, the original IEEE and The Open Group Standard
177 is the referee document. The original Standard can be obtained online
178 at http://www.opengroup.org/unix/online.html .
179IEEE/The Open Group 2003 PTHREAD_ATTR_DESTROY(3P)