---

36.2.5 POSIX Barriers ¶

A POSIX barrier works as follows: a file-local or global pthread_barrier_t object is initialized via pthread_barrier_init to require count threads to wait on it. After that, up to count-1 threads will wait on the barrier via pthread_barrier_wait. None of these calls will return until count threads are waiting via the next call to pthread_barrier_wait, at which point, all of these calls will return. The net result is that count threads will be synchronized at that point. At some point after this, the barrier is destroyed via pthread_barrier_destroy. Note that a barrier must be destroyed before being re-initialized, to ensure that all threads are properly synchronized, but need not be destroyed and re-initialized before being reused.

Function: int pthread_barrier_init (pthread_barrier_t *barrier, const pthread_barrierattr_t *attr, unsigned int count) ¶

Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

This function initializes a barrier to synchronize count threads. The barrier must be uninitialized or destroyed before it is initialized; attempting to initialize an in-use barrier results in undefined behavior.

The attr argument to pthread_barrier_init is typically NULL for a process-private barrier, but may be used to share a barrier across processes (documentation TBD).

On success, 0 is returned. On error, one of the following is returned:

EINVAL

Either count is zero, or is large enough to cause an internal overflow.

Function: int pthread_barrier_wait (pthread_barrier_t *barrier) ¶

Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

This function synchronizes threads. The first count-1 threads that wait on barrier will just wait. The next thread that waits on barrier will cause all count threads’ calls to return. The barrier must be initialized with pthread_barrier_init and not yet destroyed with pthread_barrier_destroy.

The return value of this function is PTHREAD_BARRIER_SERIAL_THREAD for one thread (it is unspecified which thread) and 0 for the remainder, for each batch of count threads synchronized. After such a batch is synchronized, the barrier will begin synchronizing the next count threads.

Function: int pthread_barrier_destroy (pthread_barrier_t *barrier) ¶

Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

Destroys barrier and releases any resources it may have allocated. A barrier must not be destroyed if any thread is waiting on it, or if it was not initialized. This call always succeeds and returns 0.