Main Page | Class Hierarchy | Alphabetical List | Class List | Directories | File List | Class Members | File Members | Related Pages

CyclicBarrier Class Reference

A synchronization aid that allows a set of threads to all wait for each other to reach a common barrier point. More...

List of all members.

Private Member Functions

void nextGeneration ()
void breakBarrier ()
int dowait (bool timed, long nanos)
 this (int parties, int(*barrierAction)()=null)
int parties ()
int wait ()
int wait (long timeout, TimeUnit unit)
bool isBroken ()
void reset ()
int getNumberWaiting ()

Private Attributes

ReentrantLock lock
Condition trip
int parties_
int(* barrierCommand )()
long generation
bool broken
int count


Detailed Description

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 delegate 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 {
     int myRow;
     Worker(int row) { myRow = row; }
     int run() {
       while (!done()) {
         processRow(myRow);
         try {
           barrier.wait(); 
         } catch (BrokenBarrierException ex) { 
           return 1; 
         }
       }
       return 0;
     }
   }

   this(float[][] matrix) {
     data = matrix;
     N = matrix.length;
     barrier = new CyclicBarrier(N, 
         delegate int() { 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 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 wait returns the arrival index of that thread at the barrier. You can then choose which thread should execute the barrier action.

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 failure, or timeout, all other threads, even those that have not yet resumed from a previous wait. will also leave abnormally via BrokenBarrierException.

Definition at line 111 of file CyclicBarrier.d.


Member Function Documentation

void nextGeneration  )  [inline, private]
 

Updates state on barrier trip and wake up everyone.

Definition at line 142 of file CyclicBarrier.d.

References Condition::notifyAll(), parties_, and trip.

Referenced by dowait().

void breakBarrier  )  [inline, private]
 

Sets barrier as broken and wake up everyone

Definition at line 151 of file CyclicBarrier.d.

References broken, Condition::notifyAll(), and trip.

Referenced by dowait().

int dowait bool  timed,
long  nanos
[inline, private]
 

Main barrier code, covering the various policies.

Definition at line 159 of file CyclicBarrier.d.

References barrierCommand, breakBarrier(), broken, count, generation, ReentrantLock::lock(), lock, nextGeneration(), trip, ReentrantLock::unlock(), and Condition::wait().

Referenced by wait().

this int  parties,
int(*)()  barrierAction = null
[inline, private]
 

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 wait before the barrier is tripped.
barrierAction the command to execute when the barrier is tripped, or null if there is no action.

Definition at line 230 of file CyclicBarrier.d.

References lock, ReentrantLock::lock(), ReentrantLock::newCondition(), parties(), and ReentrantLock.

int parties  )  [inline, private]
 

Returns the number of parties required to trip this barrier.

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

Definition at line 244 of file CyclicBarrier.d.

References parties_.

Referenced by this().

int wait  )  [inline, private]
 

Waits until all parties have invoked wait 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:

  • The last thread arrives; or
  • Some other thread times out while waiting for barrier; or
  • Some other thread invokes reset on this barrier.

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

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 parties - 1 indicates the first to arrive and zero indicates the last to arrive.

Definition at line 276 of file CyclicBarrier.d.

References dowait().

int wait long  timeout,
TimeUnit  unit
[inline, private]
 

Waits until all parties have invoked wait 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
  • The specified timeout elapses; or
  • Some other thread times out while waiting for barrier; or
  • Some other thread invokes reset on this barrier.

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

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 parties - 1 indicates the first to arrive and zero indicates the last to arrive.

Definition at line 315 of file CyclicBarrier.d.

References dowait(), and toNanos().

bool isBroken  )  [inline, private]
 

Queries if this barrier is in a broken state.

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

Definition at line 326 of file CyclicBarrier.d.

References broken, ReentrantLock::lock(), lock, and ReentrantLock::unlock().

void reset  )  [inline, private]
 

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.

Definition at line 345 of file CyclicBarrier.d.

References broken, generation, ReentrantLock::lock(), lock, Condition::notifyAll(), trip, and ReentrantLock::unlock().

int getNumberWaiting  )  [inline, private]
 

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 wait

Definition at line 369 of file CyclicBarrier.d.

References count, ReentrantLock::lock(), lock, parties_, and ReentrantLock::unlock().


Member Data Documentation

ReentrantLock lock [private]
 

The lock for guarding barrier entry

Definition at line 114 of file CyclicBarrier.d.

Referenced by dowait(), getNumberWaiting(), isBroken(), reset(), and this().

Condition trip [private]
 

Condition to wait on until tripped

Definition at line 116 of file CyclicBarrier.d.

Referenced by breakBarrier(), dowait(), nextGeneration(), and reset().

int parties_ [private]
 

The number of parties

Definition at line 118 of file CyclicBarrier.d.

Referenced by getNumberWaiting(), nextGeneration(), and parties().

int(* barrierCommand)() [private]
 

Referenced by dowait().

long generation [private]
 

The generation number. Incremented upon barrier trip. Retracted upon reset.

Definition at line 126 of file CyclicBarrier.d.

Referenced by dowait(), and reset().

bool broken [private]
 

Breakage indicator.

Definition at line 131 of file CyclicBarrier.d.

Referenced by breakBarrier(), dowait(), isBroken(), and reset().

int count [private]
 

Number of parties still waiting. Counts down from parties to 0 on each cycle.

Definition at line 137 of file CyclicBarrier.d.

Referenced by dowait(), and getNumberWaiting().


The documentation for this class was generated from the following file:
Generated on Fri Nov 11 18:44:33 2005 for Mango by  doxygen 1.4.0