mirror of https://github.com/mkerrisk/man-pages
186 lines
8.0 KiB
Plaintext
186 lines
8.0 KiB
Plaintext
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
|
.TH "PTHREAD_ATTR_DESTROY" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
|
.\" pthread_attr_destroy
|
|
.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 .
|