.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 
.TH "PTHREAD_BARRIER_WAIT" 3P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\" pthread_barrier_wait 
.SH 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.
.SH NAME
pthread_barrier_wait \- synchronize at a barrier (\fBADVANCED REALTIME
THREADS\fP)
.SH SYNOPSIS
.LP
\fB#include <pthread.h>
.br
.sp
int pthread_barrier_wait(pthread_barrier_t *\fP\fIbarrier\fP\fB);
\fP
\fB
.br
\fP
.SH DESCRIPTION
.LP
The \fIpthread_barrier_wait\fP() function shall synchronize participating
threads at the barrier referenced by \fIbarrier\fP.
The calling thread shall block until the required number of threads
have called \fIpthread_barrier_wait\fP() specifying the
barrier.
.LP
When the required number of threads have called \fIpthread_barrier_wait\fP()
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 \fIpthread_barrier_init\fP() function
that referenced it.
.LP
The constant PTHREAD_BARRIER_SERIAL_THREAD is defined in \fI<pthread.h>\fP
and
its value shall be distinct from any other value returned by \fIpthread_barrier_wait\fP().
.LP
The results are undefined if this function is called with an uninitialized
barrier.
.LP
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.
.LP
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.
.SH RETURN VALUE
.LP
Upon successful completion, the \fIpthread_barrier_wait\fP() 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.
.SH ERRORS
.LP
The \fIpthread_barrier_wait\fP() function may fail if:
.TP 7
.B EINVAL
The value specified by \fIbarrier\fP does not refer to an initialized
barrier object.
.sp
.LP
This function shall not return an error code of [EINTR].
.LP
\fIThe following sections are informative.\fP
.SH EXAMPLES
.LP
None.
.SH APPLICATION USAGE
.LP
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.
.LP
The \fIpthread_barrier_wait\fP() function is part of the Barriers
option and need not be provided on all implementations.
.SH RATIONALE
.LP
None.
.SH FUTURE DIRECTIONS
.LP
None.
.SH SEE ALSO
.LP
\fIpthread_barrier_destroy\fP(), the Base Definitions volume of
IEEE\ Std\ 1003.1-2001, \fI<pthread.h>\fP
.SH 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 .