.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 
.TH "PTHREAD_ATTR_DESTROY" 3P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\" pthread_attr_destroy 
.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 \- destroy and initialize the
thread attributes object
.SH SYNOPSIS
.LP
\fB#include <pthread.h>
.br
.sp
int pthread_attr_destroy(pthread_attr_t *\fP\fIattr\fP\fB);
.br
int pthread_attr_init(pthread_attr_t *\fP\fIattr\fP\fB); \fP
\fB
.br
\fP
.SH DESCRIPTION
.LP
The \fIpthread_attr_destroy\fP() function shall destroy a thread attributes
object. An implementation may cause
\fIpthread_attr_destroy\fP() to set \fIattr\fP to an implementation-defined
invalid value. A destroyed \fIattr\fP attributes
object can be reinitialized using \fIpthread_attr_init\fP(); the results
of otherwise referencing the object after it has been
destroyed are undefined.
.LP
The \fIpthread_attr_init\fP() function shall initialize a thread attributes
object \fIattr\fP with the default value for all
of the individual attributes used by a given implementation.
.LP
The resulting attributes object (possibly modified by setting individual
attribute values) when used by \fIpthread_create\fP() defines the
attributes of the thread created. A single attributes
object can be used in multiple simultaneous calls to \fIpthread_create\fP().
Results are undefined if \fIpthread_attr_init\fP() is called specifying
an already initialized \fIattr\fP attributes object.
.SH RETURN VALUE
.LP
Upon successful completion, \fIpthread_attr_destroy\fP() and \fIpthread_attr_init\fP()
shall return a value of 0; otherwise,
an error number shall be returned to indicate the error.
.SH ERRORS
.LP
The \fIpthread_attr_init\fP() function shall fail if:
.TP 7
.B ENOMEM
Insufficient memory exists to initialize the thread attributes object.
.sp
.LP
These functions shall not return an error code of [EINTR].
.LP
\fIThe following sections are informative.\fP
.SH EXAMPLES
.LP
None.
.SH APPLICATION USAGE
.LP
None.
.SH RATIONALE
.LP
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.
.LP
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.
.LP
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\fP() call is not required.
.LP
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.
.LP
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.
.LP
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.
.LP
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 ( \fIpthread_create\fP(),
\fIpthread_mutex_init\fP(), \fIpthread_cond_init\fP()). 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.
.LP
.IP " 2." 4
If further specialization of mutexes and condition variables is necessary,
implementations may specify additional procedures
that operate on the \fBpthread_mutex_t\fP and \fBpthread_cond_t\fP
objects (instead of on attributes objects).
.LP
.LP
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 \fBint\fP, 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.
.LP
.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).
.LP
.LP
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.
.LP
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 IEEE\ Std\ 1003.1-2001
has to be done with care so as not to affect
binary-compatibility.
.LP
Attributes objects, even if allocated by means of dynamic allocation
functions such as \fImalloc\fP(), may have their size fixed at compile
time. This means, for example, a \fIpthread_create\fP() in an implementation
with extensions to \fBpthread_attr_t\fP 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.
.SH FUTURE DIRECTIONS
.LP
None.
.SH SEE ALSO
.LP
\fIpthread_attr_getstackaddr\fP(), \fIpthread_attr_getstacksize\fP(),
\fIpthread_attr_getdetachstate\fP(), \fIpthread_create\fP(), the
Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI<pthread.h>\fP
.SH COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 6, Copyright (C) 2001-2003 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 .