pthread_attr_destroy

       thread attributes object

SYNOPSIS
       #include <pthread.h>

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


DESCRIPTION
       The pthread_attr_destroy() function shall destroy a  thread  attributes
       object.  An implementation may cause pthread_attr_destroy() to set attr
       to an implementation-defined invalid value. A destroyed attr attributes
       object  can  be reinitialized using pthread_attr_init(); the results of
       otherwise referencing the object after it has been destroyed are  unde-
       fined.

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

       The  resulting attributes object (possibly modified by setting individ-
       ual  attribute  values)  when  used  by  pthread_create()  defines  the
       attributes  of  the  thread  created. A single attributes object can be
       used in multiple simultaneous calls to pthread_create().   Results  are
       undefined  if  pthread_attr_init() is called specifying an already ini-
       tialized attr attributes object.

RETURN VALUE
       Upon     successful     completion,     pthread_attr_destroy()      and
       pthread_attr_init() shall return a value of 0; otherwise, an error num-
       ber shall be returned to indicate the error.

ERRORS
       The pthread_attr_init() function shall fail if:

       ENOMEM Insufficient memory exists to initialize the  thread  attributes
              object.


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

       The following sections are informative.

EXAMPLES
       None.

APPLICATION USAGE
       None.

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.
       in a single place and then referenced wherever threads need to be  cre-
       ated. Changes to "class" decisions become straightforward, and detailed
       analysis of each pthread_create() call is not required.

       The attributes objects are defined as opaque types as an aid to  exten-
       sibility.   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.   Imple-
       mentations  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 implementa-
       tion.

       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 ( pthread_cre-
           ate(),  pthread_mutex_init(),  pthread_cond_init()).  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  imple-
           mentation-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 pthread_mutex_t and pthread_cond_t 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 int, application  pro-
           grammers  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 cur-
           rently 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.

       allocated and released on demand.

       The attribute mechanism has been designed in large measure for extensi-
       bility.   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.

       Attributes  objects,  even  if allocated by means of dynamic allocation
       functions such as malloc(), may have their size fixed at compile  time.
       This  means,  for example, a pthread_create() in an implementation with
       extensions to pthread_attr_t cannot  look  beyond  the  area  that  the
       binary  application  assumes  is valid.  This suggests that implementa-
       tions 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.

FUTURE DIRECTIONS
       None.

SEE ALSO
       pthread_attr_getstackaddr()     ,     pthread_attr_getstacksize()     ,
       pthread_attr_getdetachstate() , pthread_create() , the Base Definitions
       volume of IEEE Std 1003.1-2001, <pthread.h>

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 .



IEEE/The Open Group                  2003              PTHREAD_ATTR_DESTROY(P)