NAME

       pthread_barrier_destroy,  pthread_barrier_init  -  destroy and initialize a barrier object
       (ADVANCED REALTIME THREADS)

SYNOPSIS

       #include <pthread.h>

       int pthread_barrier_destroy(pthread_barrier_t *barrier);
       int pthread_barrier_init(pthread_barrier_t *restrict barrier,
              const pthread_barrierattr_t *restrict attr, unsigned count);

DESCRIPTION

       The pthread_barrier_destroy() function shall destroy the barrier referenced by barrier and
       release  any resources used by the barrier. The effect of subsequent use of the barrier is
       undefined until the barrier is reinitialized by another call to pthread_barrier_init(). An
       implementation  may  use this function to set barrier to an invalid value. The results are
       undefined if pthread_barrier_destroy() is  called  when  any  thread  is  blocked  on  the
       barrier, or if this function is called with an uninitialized barrier.

       The  pthread_barrier_init()  function  shall  allocate  any  resources required to use the
       barrier referenced by barrier and shall initialize the barrier with attributes  referenced
       by attr.  If attr is NULL, the default barrier attributes shall be used; the effect is the
       same as passing the address of a  default  barrier  attributes  object.  The  results  are
       undefined  if  pthread_barrier_init()  is called when any thread is blocked on the barrier
       (that is, has  not  returned  from  the  pthread_barrier_wait()  call).  The  results  are
       undefined  if a barrier is used without first being initialized. The results are undefined
       if pthread_barrier_init() is called specifying an already initialized barrier.

       The count argument specifies the number of threads that must  call  pthread_barrier_wait()
       before  any  of them successfully return from the call.  The value specified by count must
       be greater than zero.

       If the pthread_barrier_init() function fails, the barrier shall not be initialized and the
       contents of barrier are undefined.

       Only  the  object  referenced  by  barrier may be used for performing synchronization. The
       result of referring to copies of that object  in  calls  to  pthread_barrier_destroy()  or
       pthread_barrier_wait() is undefined.

RETURN VALUE

       Upon  successful completion, these functions shall return zero; otherwise, an error number
       shall be returned to indicate the error.

ERRORS

       The pthread_barrier_destroy() function may fail if:

       EBUSY  The implementation has detected an attempt to destroy a barrier while it is in  use
              (for example, while being used in a pthread_barrier_wait() call) by another thread.

       EINVAL The value specified by barrier is invalid.

       The pthread_barrier_init() function shall fail if:

       EAGAIN The system lacks the necessary resources to initialize another barrier.

       EINVAL The value specified by count is equal to zero.

       ENOMEM Insufficient memory exists to initialize the barrier.

       The pthread_barrier_init() function may fail if:

       EBUSY  The implementation has detected an attempt to reinitialize a barrier while it is in
              use (for example, while being used in a  pthread_barrier_wait()  call)  by  another
              thread.

       EINVAL The value specified by attr is invalid.

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

       The following sections are informative.

EXAMPLES

       None.

APPLICATION USAGE

       The  pthread_barrier_destroy()  and  pthread_barrier_init()  functions  are  part  of  the
       Barriers option and need not be provided on all implementations.

RATIONALE

       None.

FUTURE DIRECTIONS

       None.

SEE ALSO

       pthread_barrier_wait() , 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 .