java.util.concurrent
Class CyclicBarrier

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:

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.

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.

CyclicBarrier

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()
before the barrier is tripped

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

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

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 an exception.

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

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 an exception

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

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. 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

public int getNumberWaiting()

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