java.util.concurrent
Class CyclicBarrier

java.lang.Object sample code for java.lang.Object definition code for java.lang.Object 
  extended by java.util.concurrent.CyclicBarrier

public class CyclicBarrier
extends Object sample code for java.lang.Object definition code for java.lang.Object

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.

A CyclicBarrier supports an optional Runnable sample code for java.lang.Runnable definition code for java.lang.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;
     barrier = new CyclicBarrier(N, 
                                 new Runnable() {
                                   public void run() { 
                                     mergeRows(...); 
                                   }
                                 });
     for (int i = 0; i < N; ++i) 
       new Thread(new Worker(i)).start();

     waitUntilDone();
   }
 }
 
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 sample code for java.lang.Runnable definition code for java.lang.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() sample code for java.util.concurrent.CyclicBarrier.await() definition code for java.util.concurrent.CyclicBarrier.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 a fast-fail 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, even those that have not yet resumed from a previous await() sample code for java.util.concurrent.CyclicBarrier.await() definition code for java.util.concurrent.CyclicBarrier.await() , will also leave abnormally via BrokenBarrierException sample code for java.util.concurrent.BrokenBarrierException definition code for java.util.concurrent.BrokenBarrierException (or InterruptedException if they too were interrupted at about the same time).

Since:
1.5
See Also:
CountDownLatch sample code for java.util.concurrent.CountDownLatch definition code for java.util.concurrent.CountDownLatch

Constructor Summary
CyclicBarrier sample code for java.util.concurrent.CyclicBarrier.CyclicBarrier(int) definition code for java.util.concurrent.CyclicBarrier.CyclicBarrier(int) (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 upon each barrier.
CyclicBarrier sample code for java.util.concurrent.CyclicBarrier.CyclicBarrier(int, java.lang.Runnable) definition code for java.util.concurrent.CyclicBarrier.CyclicBarrier(int, java.lang.Runnable) (int parties, Runnable sample code for java.lang.Runnable definition code for java.lang.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.
 
Method Summary
 int await sample code for java.util.concurrent.CyclicBarrier.await() definition code for java.util.concurrent.CyclicBarrier.await() ()
          Waits until all parties sample code for java.util.concurrent.CyclicBarrier.getParties() definition code for java.util.concurrent.CyclicBarrier.getParties() have invoked await on this barrier.
 int await sample code for java.util.concurrent.CyclicBarrier.await(long, java.util.concurrent.TimeUnit) definition code for java.util.concurrent.CyclicBarrier.await(long, java.util.concurrent.TimeUnit) (long timeout, TimeUnit sample code for java.util.concurrent.TimeUnit definition code for java.util.concurrent.TimeUnit  unit)
          Waits until all parties sample code for java.util.concurrent.CyclicBarrier.getParties() definition code for java.util.concurrent.CyclicBarrier.getParties() have invoked await on this barrier.
 int getNumberWaiting sample code for java.util.concurrent.CyclicBarrier.getNumberWaiting() definition code for java.util.concurrent.CyclicBarrier.getNumberWaiting() ()
          Returns the number of parties currently waiting at the barrier.
 int getParties sample code for java.util.concurrent.CyclicBarrier.getParties() definition code for java.util.concurrent.CyclicBarrier.getParties() ()
          Returns the number of parties required to trip this barrier.
 boolean isBroken sample code for java.util.concurrent.CyclicBarrier.isBroken() definition code for java.util.concurrent.CyclicBarrier.isBroken() ()
          Queries if this barrier is in a broken state.
 void reset sample code for java.util.concurrent.CyclicBarrier.reset() definition code for java.util.concurrent.CyclicBarrier.reset() ()
          Resets the barrier to its initial state.
 
Methods inherited from class java.lang.Object sample code for java.lang.Object definition code for java.lang.Object
clone sample code for java.lang.Object.clone() definition code for java.lang.Object.clone() , equals sample code for java.lang.Object.equals(java.lang.Object) definition code for java.lang.Object.equals(java.lang.Object) , finalize sample code for java.lang.Object.finalize() definition code for java.lang.Object.finalize() , getClass sample code for java.lang.Object.getClass() definition code for java.lang.Object.getClass() , hashCode sample code for java.lang.Object.hashCode() definition code for java.lang.Object.hashCode() , notify sample code for java.lang.Object.notify() definition code for java.lang.Object.notify() , notifyAll sample code for java.lang.Object.notifyAll() definition code for java.lang.Object.notifyAll() , toString sample code for java.lang.Object.toString() definition code for java.lang.Object.toString() , wait sample code for java.lang.Object.wait() definition code for java.lang.Object.wait() , wait sample code for java.lang.Object.wait(long) definition code for java.lang.Object.wait(long) , wait sample code for java.lang.Object.wait(long, int) definition code for java.lang.Object.wait(long, int)
 

Constructor Detail

CyclicBarrier sample code for java.util.concurrent.CyclicBarrier(int, java.lang.Runnable) definition code for java.util.concurrent.CyclicBarrier(int, java.lang.Runnable)

public CyclicBarrier(int parties,
                     Runnable sample code for java.lang.Runnable definition code for java.lang.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 - the number of threads that must invoke await() sample code for java.util.concurrent.CyclicBarrier.await() definition code for java.util.concurrent.CyclicBarrier.await() before the barrier is tripped.
barrierAction - the command to execute when the barrier is tripped, or null if there is no action.
Throws:
IllegalArgumentException sample code for java.lang.IllegalArgumentException definition code for java.lang.IllegalArgumentException - if parties is less than 1.

CyclicBarrier sample code for java.util.concurrent.CyclicBarrier(int) definition code for java.util.concurrent.CyclicBarrier(int)

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 upon each barrier.

Parameters:
parties - the number of threads that must invoke await() sample code for java.util.concurrent.CyclicBarrier.await() definition code for java.util.concurrent.CyclicBarrier.await() before the barrier is tripped.
Throws:
IllegalArgumentException sample code for java.lang.IllegalArgumentException definition code for java.lang.IllegalArgumentException - if parties is less than 1.
Method Detail

getParties sample code for java.util.concurrent.CyclicBarrier.getParties() definition code for java.util.concurrent.CyclicBarrier.getParties()

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

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

await sample code for java.util.concurrent.CyclicBarrier.await() definition code for java.util.concurrent.CyclicBarrier.await()

public int await()
          throws InterruptedException sample code for java.lang.InterruptedException definition code for java.lang.InterruptedException ,
                 BrokenBarrierException sample code for java.util.concurrent.BrokenBarrierException definition code for java.util.concurrent.BrokenBarrierException 
Waits until all parties sample code for java.util.concurrent.CyclicBarrier.getParties() definition code for java.util.concurrent.CyclicBarrier.getParties() 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 following things happens:

If the current thread:

then InterruptedException sample code for java.lang.InterruptedException definition code for java.lang.InterruptedException is thrown and the current thread's interrupted status is cleared.

If the barrier is reset() sample code for java.util.concurrent.CyclicBarrier.reset() definition code for java.util.concurrent.CyclicBarrier.reset() while any thread is waiting, or if the barrier is broken sample code for java.util.concurrent.CyclicBarrier.isBroken() definition code for java.util.concurrent.CyclicBarrier.isBroken() when await is invoked, or while any thread is waiting, then BrokenBarrierException sample code for java.util.concurrent.BrokenBarrierException definition code for java.util.concurrent.BrokenBarrierException is thrown.

If any thread is interrupted sample code for java.lang.Thread.interrupt() definition code for java.lang.Thread.interrupt() while waiting, then all other waiting threads will throw BrokenBarrierException sample code for java.util.concurrent.BrokenBarrierException definition code for java.util.concurrent.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:
the arrival index of the current thread, where index getParties() sample code for java.util.concurrent.CyclicBarrier.getParties() definition code for java.util.concurrent.CyclicBarrier.getParties() - 1 indicates the first to arrive and zero indicates the last to arrive.
Throws:
InterruptedException sample code for java.lang.InterruptedException definition code for java.lang.InterruptedException - if the current thread was interrupted while waiting
BrokenBarrierException sample code for java.util.concurrent.BrokenBarrierException definition code for java.util.concurrent.BrokenBarrierException - if another thread was interrupted 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 an exception.

await sample code for java.util.concurrent.CyclicBarrier.await(long, java.util.concurrent.TimeUnit) definition code for java.util.concurrent.CyclicBarrier.await(long, java.util.concurrent.TimeUnit)

public int await(long timeout,
                 TimeUnit sample code for java.util.concurrent.TimeUnit definition code for java.util.concurrent.TimeUnit  unit)
          throws InterruptedException sample code for java.lang.InterruptedException definition code for java.lang.InterruptedException ,
                 BrokenBarrierException sample code for java.util.concurrent.BrokenBarrierException definition code for java.util.concurrent.BrokenBarrierException ,
                 TimeoutException sample code for java.util.concurrent.TimeoutException definition code for java.util.concurrent.TimeoutException 
Waits until all parties sample code for java.util.concurrent.CyclicBarrier.getParties() definition code for java.util.concurrent.CyclicBarrier.getParties() 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:

If the current thread:

then InterruptedException sample code for java.lang.InterruptedException definition code for java.lang.InterruptedException is thrown and the current thread's interrupted status is cleared.

If the specified waiting time elapses then TimeoutException sample code for java.util.concurrent.TimeoutException definition code for java.util.concurrent.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() sample code for java.util.concurrent.CyclicBarrier.reset() definition code for java.util.concurrent.CyclicBarrier.reset() while any thread is waiting, or if the barrier is broken sample code for java.util.concurrent.CyclicBarrier.isBroken() definition code for java.util.concurrent.CyclicBarrier.isBroken() when await is invoked, or while any thread is waiting, then BrokenBarrierException sample code for java.util.concurrent.BrokenBarrierException definition code for java.util.concurrent.BrokenBarrierException is thrown.

If any thread is interrupted sample code for java.lang.Thread.interrupt() definition code for java.lang.Thread.interrupt() while waiting, then all other waiting threads will throw BrokenBarrierException sample code for java.util.concurrent.BrokenBarrierException definition code for java.util.concurrent.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 - the time to wait for the barrier
unit - the time unit of the timeout parameter
Returns:
the arrival index of the current thread, where index getParties() sample code for java.util.concurrent.CyclicBarrier.getParties() definition code for java.util.concurrent.CyclicBarrier.getParties() - 1 indicates the first to arrive and zero indicates the last to arrive.
Throws:
InterruptedException sample code for java.lang.InterruptedException definition code for java.lang.InterruptedException - if the current thread was interrupted while waiting
TimeoutException sample code for java.util.concurrent.TimeoutException definition code for java.util.concurrent.TimeoutException - if the specified timeout elapses.
BrokenBarrierException sample code for java.util.concurrent.BrokenBarrierException definition code for java.util.concurrent.BrokenBarrierException - if another thread was interrupted 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 an exception.

isBroken sample code for java.util.concurrent.CyclicBarrier.isBroken() definition code for java.util.concurrent.CyclicBarrier.isBroken()

public boolean isBroken()
Queries if this barrier is in a broken state.

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; and false otherwise.

reset sample code for java.util.concurrent.CyclicBarrier.reset() definition code for java.util.concurrent.CyclicBarrier.reset()

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 sample code for java.util.concurrent.BrokenBarrierException definition code for java.util.concurrent.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.


getNumberWaiting sample code for java.util.concurrent.CyclicBarrier.getNumberWaiting() definition code for java.util.concurrent.CyclicBarrier.getNumberWaiting()

public int getNumberWaiting()
Returns the number of parties currently waiting at the barrier. This method is primarily useful for debugging and assertions.

Returns:
the number of parties currently blocked in await() sample code for java.util.concurrent.CyclicBarrier.await() definition code for java.util.concurrent.CyclicBarrier.await()