| |||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
CyclicBarrier barrier = new CyclicBarrier(3);
Based on 65 examples
public class CyclicBarrier extends 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 {@link 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 {@link 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 {@link #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 {@link BrokenBarrierException} (or {@link InterruptedException} if they too were interrupted at about the same time).
Memory consistency effects: Actions in a thread prior to calling {@code await()} happen-before actions that are part of the barrier action, which in turn happen-before actions following a successful return from the corresponding {@code await()} in other threads.
Constructor Summary | |
---|---|
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. |
|
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. |
Method Summary | |
---|---|
int |
await() Waits until all java.util.concurrent.CyclicBarrier.getParties have invoked await on this barrier. |
int |
Waits until all java.util.concurrent.CyclicBarrier.getParties have invoked await on this barrier, or the specified waiting time elapses. |
int |
Returns the number of parties currently waiting at the barrier. |
int |
Returns the number of parties required to trip this barrier. |
boolean |
isBroken() Queries if this barrier is in a broken state. |
void |
reset() Resets the barrier to its initial state. |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Constructor Detail |
---|
public CyclicBarrier(int parties)
parties
- the number of threads that must invoke {@link #await}
before the barrier is trippedpublic CyclicBarrier(int parties, Runnable barrierAction)
parties
- the number of threads that must invoke {@link #await}
before the barrier is trippedbarrierAction
- the command to execute when the barrier is
tripped, or {@code null} if there is no actionMethod Detail |
---|
public int await() throws InterruptedException, BrokenBarrierException
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:
If the barrier is {@link #reset} while any thread is waiting, or if the barrier {@linkplain #isBroken is broken} when await is invoked, or while any thread is waiting, then {@link BrokenBarrierException} is thrown.
If any thread is {@linkplain Thread#interrupt interrupted} while waiting, then all other waiting threads will throw {@link 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.
InterruptedException
- if the current thread was interrupted
while waitingBrokenBarrierException
- 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 {@code await} was called, or the barrier
action (if present) failed due an exception.public int await(long timeout, TimeUnit unit) throws InterruptedException, BrokenBarrierException, TimeoutException
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:
If the specified waiting time elapses then {@link TimeoutException} is thrown. If the time is less than or equal to zero, the method will not wait at all.
If the barrier is {@link #reset} while any thread is waiting, or if the barrier {@linkplain #isBroken is broken} when await is invoked, or while any thread is waiting, then {@link BrokenBarrierException} is thrown.
If any thread is {@linkplain Thread#interrupt interrupted} while waiting, then all other waiting threads will throw {@link 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.
timeout
- the time to wait for the barrierunit
- the time unit of the timeout parameterInterruptedException
- if the current thread was interrupted
while waitingBrokenBarrierException
- 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 {@code await} was called, or the barrier action (if
present) failed due an exceptionTimeoutException
- if the specified timeout elapsespublic int getNumberWaiting()
public int getParties()
public boolean isBroken()
public void reset()
| |||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |