oasis-root

pthread_attr_destroy.3p (9235B)

'\" et
.TH PTHREAD_ATTR_DESTROY "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\"
.SH PROLOG
This manual page is part of the POSIX Programmer's Manual.
The Linux implementation of this interface may differ (consult
the corresponding Linux manual page for details of Linux behavior),
or the interface may not be implemented on Linux.
.\"
.SH NAME
pthread_attr_destroy,
pthread_attr_init
\(em destroy and initialize the thread attributes object
.SH SYNOPSIS
.LP
.nf
#include <pthread.h>
.P
int pthread_attr_destroy(pthread_attr_t *\fIattr\fP);
int pthread_attr_init(pthread_attr_t *\fIattr\fP);
.fi
.SH DESCRIPTION
The
\fIpthread_attr_destroy\fR()
function shall destroy a thread attributes object. An implementation
may cause
\fIpthread_attr_destroy\fR()
to set
.IR attr
to an implementation-defined invalid value. A destroyed
.IR attr
attributes object can be reinitialized using
\fIpthread_attr_init\fR();
the results of otherwise referencing the object after it
has been destroyed are undefined.
.P
The
\fIpthread_attr_init\fR()
function shall initialize a thread attributes object
.IR attr
with the default value for all of the individual attributes used by a
given implementation.
.P
The resulting attributes object (possibly modified by setting
individual attribute values) when used by
\fIpthread_create\fR()
defines the attributes of the thread created. A single attributes
object can be used in multiple simultaneous calls to
\fIpthread_create\fR().
Results are undefined if
\fIpthread_attr_init\fR()
is called specifying an already initialized
.IR attr
attributes object.
.P
The behavior is undefined if the value specified by the
.IR attr
argument to
\fIpthread_attr_destroy\fR()
does not refer to an initialized thread attributes object.
.SH "RETURN VALUE"
Upon successful completion,
\fIpthread_attr_destroy\fR()
and
\fIpthread_attr_init\fR()
shall return a value of 0; otherwise, an error number shall be returned
to indicate the error.
.SH ERRORS
The
\fIpthread_attr_init\fR()
function shall fail if:
.TP
.BR ENOMEM
Insufficient memory exists to initialize the thread attributes object.
.P
These functions shall not return an error code of
.BR [EINTR] .
.LP
.IR "The following sections are informative."
.SH EXAMPLES
None.
.SH "APPLICATION USAGE"
None.
.SH RATIONALE
Attributes objects are provided for threads, mutexes, and condition
variables as a mechanism to support probable future standardization in
these areas without requiring that the function itself be changed.
.P
Attributes objects provide clean isolation of the configurable aspects
of threads. For example, ``stack size''
is an important attribute of a thread, but it cannot be expressed
portably. When porting a threaded program, stack sizes often need to
be adjusted. The use of attributes objects can help by allowing the
changes to be isolated in a single place, rather than being spread
across every instance of thread creation.
.P
Attributes objects can be used to set up ``classes' of threads with
similar attributes; for example, ``threads with large stacks and high
priority'' or ``threads with minimal stacks''. These classes can be
defined in a single place and then referenced wherever threads need to
be created. Changes to ``class'' decisions become straightforward, and
detailed analysis of each
\fIpthread_create\fR()
call is not required.
.P
The attributes objects are defined as opaque types as an aid to
extensibility. If these objects had been specified as structures,
adding new attributes would force recompilation of all multi-threaded
programs when the attributes objects are extended; this might not be
possible if different program components were supplied by different
vendors.
.P
Additionally, opaque attributes objects present opportunities for
improving performance. Argument validity can be checked once when
attributes are set, rather than each time a thread is created.
Implementations often need to cache kernel objects that are expensive
to create. Opaque attributes objects provide an efficient mechanism to
detect when cached objects become invalid due to attribute changes.
.P
Since assignment is not necessarily defined on a given opaque type,
implementation-defined default values cannot be defined in a portable
way. The solution to this problem is to allow attributes objects to be
initialized dynamically by attributes object initialization functions,
so that default values can be supplied automatically by the
implementation.
.P
The following proposal was provided as a suggested alternative to the
supplied attributes:
.IP " 1." 4
Maintain the style of passing a parameter formed by the
bitwise-inclusive OR of flags to the initialization routines (\c
\fIpthread_create\fR(),
\fIpthread_mutex_init\fR(),
\fIpthread_cond_init\fR()).
The parameter containing the flags should be an opaque type for
extensibility. If no flags are set in the parameter, then the objects
are created with default characteristics. An implementation may
specify implementation-defined flag values and associated behavior.
.IP " 2." 4
If further specialization of mutexes and condition variables is
necessary, implementations may specify additional procedures that
operate on the
.BR pthread_mutex_t
and
.BR pthread_cond_t
objects (instead of on attributes objects).
.P
The difficulties with this solution are:
.IP " 1." 4
A bitmask is not opaque if bits have to be set into bitvector
attributes objects using explicitly-coded bitwise-inclusive OR
operations. If the set of options exceeds an
.BR int ,
application programmers need to know the location of each bit. If bits
are set or read by encapsulation (that is, get and set functions), then
the bitmask is merely an implementation of attributes objects as
currently defined and should not be exposed to the programmer.
.IP " 2." 4
Many attributes are not Boolean or very small integral values. For
example, scheduling policy may be placed in 3-bit or 4-bit, but
priority requires 5-bit or more, thereby taking up at least 8 bits out
of a possible 16 bits on machines with 16-bit integers. Because of
this, the bitmask can only reasonably control whether particular
attributes are set or not, and it cannot serve as the repository of the
value itself. The value needs to be specified as a function parameter
(which is non-extensible), or by setting a structure field (which is
non-opaque), or by get and set functions (making the bitmask a
redundant addition to the attributes objects).
.P
Stack size is defined as an optional attribute because the very notion
of a stack is inherently machine-dependent. Some implementations may
not be able to change the size of the stack, for example, and others
may not need to because stack pages may be discontiguous and can be
allocated and released on demand.
.P
The attribute mechanism has been designed in large measure for
extensibility. Future extensions to the attribute mechanism or to any
attributes object defined in this volume of POSIX.1\(hy2017 has to be done with care so
as not to affect binary-compatibility.
.P
Attributes objects, even if allocated by means of dynamic allocation
functions such as
\fImalloc\fR(),
may have their size fixed at compile time. This means, for example, a
\fIpthread_create\fR()
in an implementation with extensions to
.BR pthread_attr_t
cannot look beyond the area that the binary application assumes is
valid. This suggests that implementations should maintain a size field
in the attributes object, as well as possibly version information, if
extensions in different directions (possibly by different vendors) are
to be accommodated.
.P
If an implementation detects that the value specified by the
.IR attr
argument to
\fIpthread_attr_destroy\fR()
does not refer to an initialized thread attributes object, it is
recommended that the function should fail and report an
.BR [EINVAL] 
error.
.P
If an implementation detects that the value specified by the
.IR attr
argument to
\fIpthread_attr_init\fR()
refers to an already initialized thread attributes object, it is
recommended that the function should fail and report an
.BR [EBUSY] 
error.
.SH "FUTURE DIRECTIONS"
None.
.SH "SEE ALSO"
.ad l
.IR "\fIpthread_attr_getstacksize\fR\^(\|)",
.IR "\fIpthread_attr_getdetachstate\fR\^(\|)",
.IR "\fIpthread_create\fR\^(\|)"
.ad b
.P
The Base Definitions volume of POSIX.1\(hy2017,
.IR "\fB<pthread.h>\fP"
.\"
.SH COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1-2017, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 7, 2018 Edition,
Copyright (C) 2018 by the Institute of
Electrical and Electronics Engineers, Inc and The Open Group.
In the event of any discrepancy between this version and the original IEEE and
The Open Group Standard, the original IEEE and The Open Group Standard
is the referee document. The original Standard can be obtained online at
http://www.opengroup.org/unix/online.html .
.PP
Any typographical or formatting errors that appear
in this page are most likely
to have been introduced during the conversion of the source files to
man page format. To report such errors, see
https://www.kernel.org/doc/man-pages/reporting_bugs.html .