| java.lang.Object
 java.util.concurrent.CyclicBarrier
| CyclicBarrier | | public class CyclicBarrier (Code) | | 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 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 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
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
CyclicBarrier.await . will also leave abnormally via
BrokenBarrierException (or InterruptedException if
they too were interrupted at about the same time).
since:
1.5
See Also: CountDownLatch
author:
Doug Lea |
| Constructor 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. | | 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. |
| Method Summary | |
| public int | await()
Waits until all
CyclicBarrier.getParties parties have invoked await
on this barrier. | | public int | await(long timeout, TimeUnit unit)
Waits until all
CyclicBarrier.getParties parties have invoked await
on this barrier. | | public int | getNumberWaiting()
Returns the number of parties currently waiting at the barrier. | | public int | getParties()
Returns the number of parties required to trip this barrier. | | public boolean | isBroken()
Queries if this barrier is in a broken state. | | public void | reset()
Resets the barrier to its initial state. |
| CyclicBarrier | | public CyclicBarrier(int parties, Runnable barrierAction)(Code) | | 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 CyclicBarrier.awaitbefore the barrier is tripped.
Parameters:
barrierAction - the command to execute when the barrier istripped, or null if there is no action.
throws:
IllegalArgumentException - if parties is less than 1. |
| CyclicBarrier | | public CyclicBarrier(int parties)(Code) | | 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 CyclicBarrier.awaitbefore the barrier is tripped.
throws:
IllegalArgumentException - if parties is less than 1. |
| await | | public int await() throws InterruptedException, BrokenBarrierException(Code) | | Waits until all
CyclicBarrier.getParties 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 following things happens:
- The last thread arrives; or
- Some other thread
Thread.interrupt interrupts the current
thread; or
- Some other thread
Thread.interrupt interrupts one of the
other waiting threads; or
- Some other thread times out while waiting for barrier; or
- Some other thread invokes
CyclicBarrier.reset on this barrier.
If the current thread:
- has its interrupted status set on entry to this method; or
- is
Thread.interrupt interrupted while waiting
then
InterruptedException is thrown and the current thread's
interrupted status is cleared.
If the barrier is
CyclicBarrier.reset while any thread is waiting, or if
the barrier
CyclicBarrier.isBroken is broken when await is invoked,
or while any thread is waiting,
then
BrokenBarrierException is thrown.
If any thread is
Thread.interrupt 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.
the arrival index of the current thread, where indexCyclicBarrier.getParties() - 1 indicates the first to arrive and zero indicates the last to arrive.
throws:
InterruptedException - if the current thread was interrupted while waiting
throws:
BrokenBarrierException - if another thread wasinterrupted while the current thread was waiting, or the barrier wasreset, or the barrier was broken when await was called,or the barrier action (if present) failed due an exception. |
| await | | public int await(long timeout, TimeUnit unit) throws InterruptedException, BrokenBarrierException, TimeoutException(Code) | | Waits until all
CyclicBarrier.getParties 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
- The specified timeout elapses; or
- Some other thread
Thread.interrupt interrupts the current
thread; or
- Some other thread
Thread.interrupt interrupts one of the
other waiting threads; or
- Some other thread times out while waiting for barrier; or
- Some other thread invokes
CyclicBarrier.reset on this barrier.
If the current thread:
- has its interrupted status set on entry to this method; or
- is
Thread.interrupt interrupted while waiting
then
InterruptedException is thrown and the current thread's
interrupted status is cleared.
If the barrier is
CyclicBarrier.reset while any thread is waiting, or if
the barrier
CyclicBarrier.isBroken is broken when await is invoked,
or while any thread is waiting,
then
BrokenBarrierException is thrown.
If any thread is
Thread.interrupt 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 - the time to wait for the barrier
Parameters:
unit - the time unit of the timeout parameter the arrival index of the current thread, where indexCyclicBarrier.getParties() - 1 indicates the first to arrive and zero indicates the last to arrive.
throws:
InterruptedException - if the current thread was interrupted while waiting
throws:
TimeoutException - if the specified timeout elapses.
throws:
BrokenBarrierException - if another thread wasinterrupted while the current thread was waiting, or the barrier wasreset, or the barrier was broken when await was called,or the barrier action (if present) failed due an exception. |
| getNumberWaiting | | public int getNumberWaiting()(Code) | | Returns the number of parties currently waiting at the barrier.
This method is primarily useful for debugging and assertions.
the number of parties currently blocked in CyclicBarrier.await |
| getParties | | public int getParties()(Code) | | Returns the number of parties required to trip this barrier.
the number of parties required to trip this barrier. |
| isBroken | | public boolean isBroken()(Code) | | Queries if this barrier is in a broken state.
true if one or more parties broke out of thisbarrier due to interruption or timeout since construction orthe last reset, or a barrier action failed due to an exception; and false otherwise. |
| reset | | public void reset()(Code) | | 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.
|
|
|