1PTHREAD_ATTR_DESTROY(3P)   POSIX Programmer's Manual  PTHREAD_ATTR_DESTROY(3P)
2
3
4

PROLOG

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

NAME

12       pthread_attr_destroy, pthread_attr_init — destroy  and  initialize  the
13       thread attributes object
14

SYNOPSIS

16       #include <pthread.h>
17
18       int pthread_attr_destroy(pthread_attr_t *attr);
19       int pthread_attr_init(pthread_attr_t *attr);
20

DESCRIPTION

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
29       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
33       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
40       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

RETURN VALUE

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

ERRORS

50       The pthread_attr_init() function shall fail if:
51
52       ENOMEM Insufficient  memory  exists to initialize the thread attributes
53              object.
54
55       These functions shall not return an error code of [EINTR].
56
57       The following sections are informative.
58

EXAMPLES

60       None.
61

APPLICATION USAGE

63       None.
64

RATIONALE

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
70       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
78       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
85       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
91       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
98       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
105       The  following  proposal was provided as a suggested alternative to the
106       supplied attributes:
107
108        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
116        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
121       The difficulties with this solution are:
122
123        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
131        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
142       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
148       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
153       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
162       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
167       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

FUTURE DIRECTIONS

173       None.
174

SEE ALSO

176       pthread_attr_getstacksize(), pthread_attr_getdetachstate(),
177       pthread_create()
178
179       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
192       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 .
196
197
198
199IEEE/The Open Group                  2017             PTHREAD_ATTR_DESTROY(3P)
Impressum