pthread_barrier_wait Subroutine

Purpose

Synchronizes threads at a barrier.

Syntax

#include <pthread.h>

int pthread_barrier_wait(pthread_barrier_t *barrier);

Description

The pthread_barrier_wait subroutine synchronizes participating threads at the barrier referenced by barrier. The calling thread blocks until the required number of threads have called pthread_barrier_waitspecifying the barrier.

When the required number of threads have called pthread_barrier_waitspecifying the barrier, the constant PTHREAD_BARRIER_SERIAL_THREAD is returned to one unspecified thread and 0 is returned to the remaining threads. At this point, the barrier resets 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 is 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 resumes 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 continues as normal from the completed barrier wait. Until the thread in the signal handler returns from it, other threads might proceed past the barrier after they have all reached it.

Note: When the required number of threads has called pthread_barrier_wait, the PTHREAD_BARRIER_SERIAL_THREAD constant is returned by the last pthread that called pthread_barrier_wait. Furthermore, if a thread is in a signal handler while waiting and all the required threads have reached the barrier, the other threads can proceed past the barrier.

A thread that has blocked on a barrier does 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 is determined by the scheduling policy.

Parameters

Item	Description
barrier	Points to the barrier where participating threads wait.

Return Values

Upon successful completion, pthread_barrier_wait returns PTHREAD_BARRIER_SERIAL_THREAD for a single (arbitrary) thread synchronized at the barrier and 0 for the other threads. Otherwise, an error number is returned to indicate the error.

Error Codes

The pthread_barrier_destroy subroutine can fail if:

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

This function does not return an error code of EINTR.