PTHREAD_ATTR_DESTROY(3)    POSIX Programmer's Manual   PTHREAD_ATTR_DESTROY(3)



PPRROOLLOOGG
       This manual page is part of the POSIX Programmer's Manual.  The OS
       implementation of this interface may differ (consult the corresponding
       OS manual page for details of OS behavior), or the interface may not be
       implemented on OS.


NNAAMMEE
       pthread_attr_destroy, pthread_attr_init -- destroy and initialize the
       thread attributes object

SSYYNNOOPPSSIISS
       #include <pthread.h>

       int pthread_attr_destroy(pthread_attr_t *_a_t_t_r);
       int pthread_attr_init(pthread_attr_t *_a_t_t_r);

DDEESSCCRRIIPPTTIIOONN
       The _p_t_h_r_e_a_d___a_t_t_r___d_e_s_t_r_o_y() function shall destroy a thread attributes
       object. An implementation may cause _p_t_h_r_e_a_d___a_t_t_r___d_e_s_t_r_o_y() to set _a_t_t_r
       to an implementation-defined invalid value. A destroyed _a_t_t_r attributes
       object can be reinitialized using _p_t_h_r_e_a_d___a_t_t_r___i_n_i_t(); the results of
       otherwise referencing the object after it has been destroyed are
       undefined.

       The _p_t_h_r_e_a_d___a_t_t_r___i_n_i_t() function shall initialize a thread attributes
       object _a_t_t_r with the default value for all of the individual attributes
       used by a given implementation.

       The resulting attributes object (possibly modified by setting
       individual attribute values) when used by _p_t_h_r_e_a_d___c_r_e_a_t_e() defines the
       attributes of the thread created. A single attributes object can be
       used in multiple simultaneous calls to _p_t_h_r_e_a_d___c_r_e_a_t_e().  Results are
       undefined if _p_t_h_r_e_a_d___a_t_t_r___i_n_i_t() is called specifying an already
       initialized _a_t_t_r attributes object.

       The behavior is undefined if the value specified by the _a_t_t_r argument
       to _p_t_h_r_e_a_d___a_t_t_r___d_e_s_t_r_o_y() does not refer to an initialized thread
       attributes object.

RREETTUURRNN VVAALLUUEE
       Upon successful completion, _p_t_h_r_e_a_d___a_t_t_r___d_e_s_t_r_o_y() and
       _p_t_h_r_e_a_d___a_t_t_r___i_n_i_t() shall return a value of 0; otherwise, an error
       number shall be returned to indicate the error.

EERRRROORRSS
       The _p_t_h_r_e_a_d___a_t_t_r___i_n_i_t() function shall fail if:

       EENNOOMMEEMM Insufficient memory exists to initialize the thread attributes
              object.

       These functions shall not return an error code of [[EEIINNTTRR]].

       _T_h_e _f_o_l_l_o_w_i_n_g _s_e_c_t_i_o_n_s _a_r_e _i_n_f_o_r_m_a_t_i_v_e_.

EEXXAAMMPPLLEESS
       None.

AAPPPPLLIICCAATTIIOONN UUSSAAGGEE
       None.

RRAATTIIOONNAALLEE
       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.

       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.

       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 _p_t_h_r_e_a_d___c_r_e_a_t_e() call is not required.

       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.

       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.

       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.

       The following proposal was provided as a suggested alternative to the
       supplied attributes:

        1. Maintain the style of passing a parameter formed by the bitwise-
           inclusive OR of flags to the initialization routines
           (_p_t_h_r_e_a_d___c_r_e_a_t_e(), _p_t_h_r_e_a_d___m_u_t_e_x___i_n_i_t(), _p_t_h_r_e_a_d___c_o_n_d___i_n_i_t()).  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.

        2. If further specialization of mutexes and condition variables is
           necessary, implementations may specify additional procedures that
           operate on the pptthhrreeaadd__mmuutteexx__tt and pptthhrreeaadd__ccoonndd__tt objects (instead
           of on attributes objects).

       The difficulties with this solution are:

        1. 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 iinntt, 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.

        2. 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).

       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.

       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-2008 has to be done
       with care so as not to affect binary-compatibility.

       Attributes objects, even if allocated by means of dynamic allocation
       functions such as _m_a_l_l_o_c(), may have their size fixed at compile time.
       This means, for example, a _p_t_h_r_e_a_d___c_r_e_a_t_e() in an implementation with
       extensions to pptthhrreeaadd__aattttrr__tt 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.

       If an implementation detects that the value specified by the _a_t_t_r
       argument to _p_t_h_r_e_a_d___a_t_t_r___d_e_s_t_r_o_y() does not refer to an initialized
       thread attributes object, it is recommended that the function should
       fail and report an [[EEIINNVVAALL]] error.

       If an implementation detects that the value specified by the _a_t_t_r
       argument to _p_t_h_r_e_a_d___a_t_t_r___i_n_i_t() refers to an already initialized thread
       attributes object, it is recommended that the function should fail and
       report an [[EEBBUUSSYY]] error.

FFUUTTUURREE DDIIRREECCTTIIOONNSS
       None.

SSEEEE AALLSSOO
       _p_t_h_r_e_a_d___a_t_t_r___g_e_t_s_t_a_c_k_s_i_z_e(), _p_t_h_r_e_a_d___a_t_t_r___g_e_t_d_e_t_a_c_h_s_t_a_t_e(),
       _p_t_h_r_e_a_d___c_r_e_a_t_e()

       The Base Definitions volume of POSIX.1-2008, <<pptthhrreeaadd..hh>>

CCOOPPYYRRIIGGHHTT
       Portions of this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
       -- Portable Operating System Interface (POSIX), The Open Group Base
       Specifications Issue 7, Copyright (C) 2013 by the Institute of
       Electrical and Electronics Engineers, Inc and The Open Group.  (This is
       POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) 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.unix.org/online.html .

       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 .



IEEE/The Open Group                  2013              PTHREAD_ATTR_DESTROY(3)
