barrier(3synch)

barrier: barrier_init, barrier_wait, barrier_destroy, _barrier_spin_init, _barrier_spin, _barrier_spin_destroy -- overview of barrier synchronization routines

Synopsis

   cc [options] -Kthread file
   
   #include <synch.h>
   

   int barrier_init(barrier_t *barrier, int count, int type, void *arg);
   

   int barrier_wait(barrier_t *barrier);
   

   int barrier_destroy(barrier_t *barrier);
   

   int _barrier_spin_init(barrier_spin_t *barrier, int count, void *arg)
   

   int _barrier_spin(barrier_spin_t *barrier);
   

   int _barrier_spin_destroy(barrier_spin_t *barrier);

Parameters

barrier: pointer to barrier to be initialized, waited at, or destroyed
count: number of threads to use the barrier for synchronization
type: USYNC_THREAD or USYNC_PROCESS
arg: NULL (reserved for future use)

Description

Barriers provide a simple coordination mechanism for threads. Threads wait at a barrier until a specified number of threads have reached the barrier, then resume execution.

There are two types of barriers: ``blocking'' and spinning. Threads waiting at a blocking barrier are put to sleep, or blocked, until the specified number of threads have reached the barrier. Threads waiting at a spinning barrier busy-wait, or ``spin'', until the specified number of threads have reached the barrier.

When a thread calls barrier_wait (for a blocking barrier) or _barrier_spin (for a spinning barrier), it is said to have ``reached the barrier''.

The Threads Library provides three routines for blocking barriers and three for spinning barriers. These are outlined below and described in more detail on individual manual pages.

Blocking barrier routines

barrier_init(3synch)

barrier_init initializes the blocking barrier pointed to by barrier to be of type type and to synchronize count threads.

Blocking barriers are initialized to be one of two types: USYNC_THREAD or USYNC_PROCESS. USYNC_THREAD barriers are available only to threads within the current process. USYNC_PROCESS barriers can be used by threads in different processes.

barrier_wait(3synch)

barrier_wait blocks the calling thread at a blocking barrier until count threads reach the barrier. When the last thread reaches the barrier, all count blocked threads are released from the barrier and are allowed to resume execution. The barrier is reset after the waiting threads are released.

barrier_destroy(3synch)

barrier_destroy destroys the blocking barrier pointed to by barrier. This includes invalidating the barrier and freeing any associated implementation-allocated dynamic resources.

Spinning barrier routines

_barrier_spin_init(3synch)

_barrier_spin_init initializes the spinning barrier pointed to by barrier to synchronize count threads.

_barrier_spin(3synch)

_barrier_spin makes the calling thread busy-wait, or ``spin'', at a spinning barrier until count threads reach the barrier. When the last thread reaches the barrier, all count spinning threads are released from the barrier and allowed to resume execution. The barrier is reset after the waiting threads are released.

_barrier_spin_destroy(3synch)

_barrier_spin_destroy destroys the barrier pointed to by barrier. This includes invalidating the barrier and freeing any associated implementation-allocated dynamic resources.

Usage

Because spinning barriers waste resources, most applications should use blocking barriers instead of spinning barriers. Spinning barriers should only be used when all participating threads will reach the barrier at approximately the same time.

Warnings

Spinning barriers should never be used on a single processor system.

References

Intro(3synch), barrier_init(3synch), barrier_destroy(3synch), _barrier_spin(3synch), _barrier_spin_destroy(3synch), _barrier_spin_init(3synch), barrier_wait(3synch)