NAME

       pthread_barrier_wait - synchronize at a barrier (ADVANCED REALTIME THREADS)

SYNOPSIS

       #include <pthread.h>

       int pthread_barrier_wait(pthread_barrier_t *barrier);

DESCRIPTION

       The pthread_barrier_wait() function shall synchronize participating threads at the barrier
       referenced by barrier.  The calling thread  shall  block  until  the  required  number  of
       threads have called pthread_barrier_wait() specifying the barrier.

       When  the  required  number  of  threads have called pthread_barrier_wait() specifying the
       barrier, the constant PTHREAD_BARRIER_SERIAL_THREAD shall be returned to  one  unspecified
       thread  and  zero  shall  be returned to each of the remaining threads. At this point, the
       barrier  shall  be  reset  to  the  state  it  had  as  a  result  of  the   most   recent
       pthread_barrier_init() function that referenced it.

       The  constant  PTHREAD_BARRIER_SERIAL_THREAD is defined in <pthread.h> and its value shall
       be distinct from any other value returned by pthread_barrier_wait().

       The results are undefined if this function is called with an uninitialized barrier.

       If a signal is delivered to a thread blocked on a barrier, upon  return  from  the  signal
       handler  the  thread  shall  resume  waiting  at  the  barrier if the barrier wait has not
       completed (that is, if the required number of threads have  not  arrived  at  the  barrier
       during  the  execution  of  the  signal  handler); otherwise, the thread shall continue as
       normal from the completed barrier wait. Until the thread in  the  signal  handler  returns
       from  it,  it  is unspecified whether other threads may proceed past the barrier once they
       have all reached it.

       A thread that has blocked on a barrier shall not prevent  any  unblocked  thread  that  is
       eligible  to  use the same processing resources from eventually making forward progress in
       its execution.  Eligibility for processing resources shall be determined by the scheduling
       policy.

RETURN VALUE

       Upon   successful   completion,   the   pthread_barrier_wait()   function   shall   return
       PTHREAD_BARRIER_SERIAL_THREAD for a single (arbitrary) thread synchronized at the  barrier
       and  zero  for  each of the other threads. Otherwise, an error number shall be returned to
       indicate the error.

ERRORS

       The pthread_barrier_wait() function may fail if:

       EINVAL The value specified by barrier does not refer to an initialized barrier object.

       This function shall not return an error code of [EINTR].

       The following sections are informative.

EXAMPLES

       None.

APPLICATION USAGE

       Applications using this function may be subject to priority inversion, as discussed in the
       Base Definitions volume of IEEE Std 1003.1-2001, Section 3.285, Priority Inversion.

       The  pthread_barrier_wait()  function  is  part  of  the  Barriers  option and need not be
       provided on all implementations.

RATIONALE

       None.

FUTURE DIRECTIONS

       None.

SEE ALSO

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