pthread_attr_destroy(3p) - phpMan

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

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.
NAME
       pthread_attr_destroy, pthread_attr_init - destroy  and  initialize  the
       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.
       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 cre-
       ation.
       Attributes objects can be used to set up "classes' of threads with sim-
       ilar  attributes; for example, "threads with large stacks and high pri-
       ority" or "threads with minimal stacks". These classes can  be  defined
       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.
           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 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(3P)