OpenJDK 27 · java.util.concurrent.CyclicBarrier · APIdia, the JavaDoc alternative

A synchronization aid that allows a set of threads to all wait for each other to reach a common barrier point. CyclicBarriers are useful in programs involving a fixed sized party of threads that must occasionally wait for each other. The barrier is called cyclic because it can be re-used after the waiting threads are released. If you need support for variable numbers of parties per cycle, alternate actions on exceptions, termination control, contention control, or status monitoring, use the more flexible Phaser class.

A CyclicBarrier supports an optional Runnable command that is run once per barrier point, after the last thread in the party arrives, but before any threads are released. This barrier action is useful for updating shared-state before any of the parties continue.

Sample usage: Here is an example of using a barrier in a parallel decomposition design:

 class Solver {
  final int N;
  final float[][] data;
  final CyclicBarrier barrier;

  class Worker implements Runnable {
    int myRow;
    Worker(int row) { myRow = row; }
    public void run() {
      while (!done()) {
        processRow(myRow);

        try {
          barrier.await();
        } catch (InterruptedException ex) {
          return;
        } catch (BrokenBarrierException ex) {
          return;
        }
      }
    }
  }

  public Solver(float[][] matrix) {
    data = matrix;
    N = matrix.length;
    Runnable barrierAction = () -> mergeRows(...);
    barrier = new CyclicBarrier(N, barrierAction);

    List<Thread> threads = new ArrayList<>(N);
    for (int i = 0; i < N; i++) {
      Thread thread = new Thread(new Worker(i));
      threads.add(thread);
      thread.start();
    }

    // wait until done
    for (Thread thread : threads)
      try {
        thread.join();
      } catch (InterruptedException ex) { }
  }
}

Here, each worker thread processes a row of the matrix, then waits at the barrier until all rows have been processed. When all rows are processed the supplied Runnable barrier action is executed and merges the rows. If the merger determines that a solution has been found then done() will return true and each worker will terminate.

If the barrier action does not rely on the parties being suspended when it is executed, then any of the threads in the party could execute that action when it is released. To facilitate this, each invocation of await returns the arrival index of that thread at the barrier. You can then choose which thread should execute the barrier action, for example:

 if (barrier.await() == 0) {
  // log the completion of this iteration
}

The CyclicBarrier uses an all-or-none breakage model for failed synchronization attempts: If a thread leaves a barrier point prematurely because of interruption, failure, or timeout, all other threads waiting at that barrier point will also leave abnormally via BrokenBarrierException (or InterruptedException if they too were interrupted at about the same time).

Memory consistency effects: Actions in a thread prior to calling await() happen-before actions that are part of the barrier action, which in turn happen-before actions following a successful return from the corresponding await() in other threads.

Nested and Inner Type Summary

Modifier and Type	Class and Description
private static class	CyclicBarrier.Generation Each use of the barrier is represented as a generation instance.

Field Summary

Modifier and Type	Field and Description
private final Runnable	barrierCommand The command to run when tripped
private int	count Number of parties still waiting.
private CyclicBarrier.Generation	generation The current generation
private final ReentrantLock	lock The lock for guarding barrier entry
private final int	parties The number of parties
private final Condition	trip Condition to wait on until tripped

Constructor Summary

Access Constructor and Description

Access	Constructor and Description
public	CyclicBarrier(int the number of threads that must invoke `await` before the barrier is tripped parties, Runnable the command to execute when the barrier is tripped, or `null` if there is no action barrierAction) Creates a new `CyclicBarrier` that will trip when the given number of parties (threads) are waiting upon it, and which will execute the given barrier action when the barrier is tripped, performed by the last thread entering the barrier.
public	CyclicBarrier(int the number of threads that must invoke `await` before the barrier is tripped parties) Creates a new `CyclicBarrier` that will trip when the given number of parties (threads) are waiting upon it, and does not perform a predefined action when the barrier is tripped.

public

CyclicBarrier(int

the number of threads that must invoke await before the barrier is tripped

parties, Runnable

the command to execute when the barrier is tripped, or null if there is no action

barrierAction)

Creates a new CyclicBarrier that will trip when the given number of parties (threads) are waiting upon it, and which will execute the given barrier action when the barrier is tripped, performed by the last thread entering the barrier.

public

CyclicBarrier(int

the number of threads that must invoke await before the barrier is tripped

parties)

Creates a new CyclicBarrier that will trip when the given number of parties (threads) are waiting upon it, and does not perform a predefined action when the barrier is tripped.

Method Summary

Modifier and Type	Method and Description
public int	Returns: the arrival index of the current thread, where index `getParties() - 1` indicates the first to arrive and zero indicates the last to arrive await() Waits until all parties have invoked `await` on this barrier.
public int	Returns: the arrival index of the current thread, where index `getParties() - 1` indicates the first to arrive and zero indicates the last to arrive await(long the time to wait for the barrier timeout, TimeUnit the time unit of the timeout parameter unit) Waits until all parties have invoked `await` on this barrier, or the specified waiting time elapses.
private void	breakBarrier() Sets current barrier generation as broken and wakes up everyone.
private int	dowait(boolean timed, long nanos) Main barrier code, covering the various policies.
public int	Returns: the number of parties currently blocked in `await` getNumberWaiting() Returns the number of parties currently waiting at the barrier.
public int	Returns: the number of parties required to trip this barrier getParties() Returns the number of parties required to trip this barrier.
public boolean	Returns: `true` if one or more parties broke out of this barrier due to interruption or timeout since construction or the last reset, or a barrier action failed due to an exception; `false` otherwise. isBroken() Queries if this barrier is in a broken state.
private void	nextGeneration() Updates state on barrier trip and wakes up everyone.
public void	reset() Resets the barrier to its initial state.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

barrierCommand	back to summary
private final Runnable barrierCommand The command to run when tripped

count	back to summary
private int count Number of parties still waiting. Counts down from parties to 0 on each generation. It is reset to parties on each new generation or when broken.

generation	back to summary
private CyclicBarrier.Generation generation The current generation

lock	back to summary
private final ReentrantLock lock The lock for guarding barrier entry

parties	back to summary
private final int parties The number of parties

trip	back to summary
private final Condition trip Condition to wait on until tripped

Constructor Detail

CyclicBarrier back to summary

CyclicBarrier	back to summary
public CyclicBarrier(int parties, Runnable barrierAction) Creates a new `CyclicBarrier` that will trip when the given number of parties (threads) are waiting upon it, and which will execute the given barrier action when the barrier is tripped, performed by the last thread entering the barrier. Parameters parties:int the number of threads that must invoke `await` before the barrier is tripped barrierAction:Runnable the command to execute when the barrier is tripped, or `null` if there is no action Exceptions IllegalArgumentException: if `parties` is less than 1

public CyclicBarrier(int parties, Runnable barrierAction)

Parameters

parties:int: the number of threads that must invoke await before the barrier is tripped
barrierAction:Runnable: the command to execute when the barrier is tripped, or null if there is no action

Exceptions

IllegalArgumentException:: if parties is less than 1

CyclicBarrier back to summary

CyclicBarrier	back to summary
public CyclicBarrier(int parties) Creates a new `CyclicBarrier` that will trip when the given number of parties (threads) are waiting upon it, and does not perform a predefined action when the barrier is tripped. Parameters parties:int the number of threads that must invoke `await` before the barrier is tripped Exceptions IllegalArgumentException: if `parties` is less than 1

public CyclicBarrier(int parties)

Creates a new CyclicBarrier that will trip when the given number of parties (threads) are waiting upon it, and does not perform a predefined action when the barrier is tripped.

Parameters

parties:int: the number of threads that must invoke await before the barrier is tripped

Exceptions

IllegalArgumentException:: if parties is less than 1

Method Detail

await back to summary

await	back to summary
public int await() throws InterruptedException, BrokenBarrierException Waits until all parties have invoked `await` on this barrier. If the current thread is not the last to arrive then it is disabled for thread scheduling purposes and lies dormant until one of the following things happens: The last thread arrives; or Some other thread interrupts the current thread; or Some other thread interrupts one of the other waiting threads; or Some other thread times out while waiting for barrier; or Some other thread invokes `reset` on this barrier. If the current thread: has its interrupted status set on entry to this method; or is interrupted while waiting then `InterruptedException` is thrown and the current thread's interrupted status is cleared. If the barrier is `reset` while any thread is waiting, or if the barrier is broken when `await` is invoked, or while any thread is waiting, then `BrokenBarrierException` is thrown. If any thread is interrupted while waiting, then all other waiting threads will throw `BrokenBarrierException` and the barrier is placed in the broken state. If the current thread is the last thread to arrive, and a non-null barrier action was supplied in the constructor, then the current thread runs the action before allowing the other threads to continue. If an exception occurs during the barrier action then that exception will be propagated in the current thread and the barrier is placed in the broken state. Returns:int the arrival index of the current thread, where index `getParties() - 1` indicates the first to arrive and zero indicates the last to arrive Exceptions InterruptedException: if the current thread was interrupted while waiting BrokenBarrierException: if another thread was interrupted or timed out while the current thread was waiting, or the barrier was reset, or the barrier was broken when `await` was called, or the barrier action (if present) failed due to an exception

public int await() throws InterruptedException, BrokenBarrierException

Waits until all parties have invoked await on this barrier.

If the current thread is not the last to arrive then it is disabled for thread scheduling purposes and lies dormant until one of the following things happens:

The last thread arrives; or
Some other thread interrupts the current thread; or
Some other thread interrupts one of the other waiting threads; or
Some other thread times out while waiting for barrier; or
Some other thread invokes reset on this barrier.

If the current thread:

has its interrupted status set on entry to this method; or
is interrupted while waiting

then InterruptedException is thrown and the current thread's interrupted status is cleared.

If the barrier is reset while any thread is waiting, or if the barrier is broken when await is invoked, or while any thread is waiting, then BrokenBarrierException is thrown.

If any thread is interrupted while waiting, then all other waiting threads will throw BrokenBarrierException and the barrier is placed in the broken state.

If the current thread is the last thread to arrive, and a non-null barrier action was supplied in the constructor, then the current thread runs the action before allowing the other threads to continue. If an exception occurs during the barrier action then that exception will be propagated in the current thread and the barrier is placed in the broken state.

Returns:int

the arrival index of the current thread, where index getParties() - 1 indicates the first to arrive and zero indicates the last to arrive

Exceptions

InterruptedException:: if the current thread was interrupted while waiting
BrokenBarrierException:: if another thread was interrupted or timed out while the current thread was waiting, or the barrier was reset, or the barrier was broken when await was called, or the barrier action (if present) failed due to an exception

await back to summary

await	back to summary
public int await(long timeout, TimeUnit unit) throws InterruptedException, BrokenBarrierException, TimeoutException Waits until all parties have invoked `await` on this barrier, or the specified waiting time elapses. If the current thread is not the last to arrive then it is disabled for thread scheduling purposes and lies dormant until one of the following things happens: The last thread arrives; or The specified timeout elapses; or Some other thread interrupts the current thread; or Some other thread interrupts one of the other waiting threads; or Some other thread times out while waiting for barrier; or Some other thread invokes `reset` on this barrier. If the current thread: has its interrupted status set on entry to this method; or is interrupted while waiting then `InterruptedException` is thrown and the current thread's interrupted status is cleared. If the specified waiting time elapses then `TimeoutException` is thrown. If the time is less than or equal to zero, the method will not wait at all. If the barrier is `reset` while any thread is waiting, or if the barrier is broken when `await` is invoked, or while any thread is waiting, then `BrokenBarrierException` is thrown. If any thread is interrupted while waiting, then all other waiting threads will throw `BrokenBarrierException` and the barrier is placed in the broken state. If the current thread is the last thread to arrive, and a non-null barrier action was supplied in the constructor, then the current thread runs the action before allowing the other threads to continue. If an exception occurs during the barrier action then that exception will be propagated in the current thread and the barrier is placed in the broken state. Parameters timeout:long the time to wait for the barrier unit:TimeUnit the time unit of the timeout parameter Returns:int the arrival index of the current thread, where index `getParties() - 1` indicates the first to arrive and zero indicates the last to arrive Exceptions InterruptedException: if the current thread was interrupted while waiting BrokenBarrierException: if another thread was interrupted or timed out while the current thread was waiting, or the barrier was reset, or the barrier was broken when `await` was called, or the barrier action (if present) failed due to an exception TimeoutException: if the specified timeout elapses. In this case the barrier will be broken.

public int await(long timeout, TimeUnit unit) throws InterruptedException, BrokenBarrierException, TimeoutException

Waits until all parties have invoked await on this barrier, or the specified waiting time elapses.

If the current thread is not the last to arrive then it is disabled for thread scheduling purposes and lies dormant until one of the following things happens:

The last thread arrives; or
The specified timeout elapses; or
Some other thread interrupts the current thread; or
Some other thread interrupts one of the other waiting threads; or
Some other thread times out while waiting for barrier; or
Some other thread invokes reset on this barrier.

If the current thread:

has its interrupted status set on entry to this method; or
is interrupted while waiting

then InterruptedException is thrown and the current thread's interrupted status is cleared.

If the specified waiting time elapses then TimeoutException is thrown. If the time is less than or equal to zero, the method will not wait at all.

If the barrier is reset while any thread is waiting, or if the barrier is broken when await is invoked, or while any thread is waiting, then BrokenBarrierException is thrown.

If any thread is interrupted while waiting, then all other waiting threads will throw BrokenBarrierException and the barrier is placed in the broken state.

Parameters

timeout:long: the time to wait for the barrier
unit:TimeUnit: the time unit of the timeout parameter

Returns:int

the arrival index of the current thread, where index getParties() - 1 indicates the first to arrive and zero indicates the last to arrive

Exceptions

InterruptedException:: if the current thread was interrupted while waiting
BrokenBarrierException:: if another thread was interrupted or timed out while the current thread was waiting, or the barrier was reset, or the barrier was broken when await was called, or the barrier action (if present) failed due to an exception
TimeoutException:: if the specified timeout elapses. In this case the barrier will be broken.

breakBarrier	back to summary
private void breakBarrier() Sets current barrier generation as broken and wakes up everyone. Called only while holding lock.

dowait	back to summary
private int dowait(boolean timed, long nanos) throws InterruptedException, BrokenBarrierException, TimeoutException Main barrier code, covering the various policies.

getNumberWaiting back to summary

getNumberWaiting	back to summary
public int getNumberWaiting() Returns the number of parties currently waiting at the barrier. This method is primarily useful for debugging and assertions. Returns:int the number of parties currently blocked in `await`

public int getNumberWaiting()

Returns the number of parties currently waiting at the barrier. This method is primarily useful for debugging and assertions.

Returns:int: the number of parties currently blocked in await

getParties	back to summary
public int getParties() Returns the number of parties required to trip this barrier. Returns:int the number of parties required to trip this barrier

getParties

back to summary

public int getParties()

Returns the number of parties required to trip this barrier.

Returns:int: the number of parties required to trip this barrier

isBroken back to summary

isBroken	back to summary
public boolean isBroken() Queries if this barrier is in a broken state. Returns:boolean `true` if one or more parties broke out of this barrier due to interruption or timeout since construction or the last reset, or a barrier action failed due to an exception; `false` otherwise.

public boolean isBroken()

Queries if this barrier is in a broken state.

Returns:boolean: true if one or more parties broke out of this barrier due to interruption or timeout since construction or the last reset, or a barrier action failed due to an exception; false otherwise.

nextGeneration	back to summary
private void nextGeneration() Updates state on barrier trip and wakes up everyone. Called only while holding lock.

reset back to summary

reset	back to summary
public void reset() Resets the barrier to its initial state. If any parties are currently waiting at the barrier, they will return with a `BrokenBarrierException`. Note that resets after a breakage has occurred for other reasons can be complicated to carry out; threads need to re-synchronize in some other way, and choose one to perform the reset. It may be preferable to instead create a new barrier for subsequent use.

public void reset()

Resets the barrier to its initial state. If any parties are currently waiting at the barrier, they will return with a BrokenBarrierException. Note that resets after a breakage has occurred for other reasons can be complicated to carry out; threads need to re-synchronize in some other way, and choose one to perform the reset. It may be preferable to instead create a new barrier for subsequent use.

public Class CyclicBarrier

Nested and Inner Type Summary

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

private Class CyclicBarrier.Generation

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail