org.terracotta.coordination
Interface Barrier

All Known Implementing Classes:

CyclicBarrier

public interface Barrier

Barriers serve as synchronization points for groups of threads that must occasionally wait for each other. Barriers may support any of several methods that accomplish this synchronization. This interface merely expresses their minimal commonalities:

• Every barrier is defined for a given number of parties -- the number of threads that must meet at the barrier point. (In all current implementations, this value is fixed upon construction of the Barrier.)
• A barrier can become broken if one or more threads leave a barrier point prematurely, generally due to interruption or timeout. Corresponding synchronization methods in barriers fail, throwing BrokenBarrierException for other threads when barriers are in broken states.

[ Introduction to this package. ]

Method Summary

int	await() Enter barrier and wait for the other parties()-1 threads.
int	await(long msecs) Enter barrier and wait at most msecs for the other parties()-1 threads.
int	getParties() Return the number of parties that must meet per barrier point.
boolean	isBroken() Returns true if the barrier has been compromised by threads leaving the barrier before a synchronization point (normally due to interruption or timeout).
void	reset() Reset to initial state.

Method Detail

getParties

int getParties()

Return the number of parties that must meet per barrier point. The number of parties is always at least 1.

isBroken

boolean isBroken()

Returns true if the barrier has been compromised by threads leaving the barrier before a synchronization point (normally due to interruption or timeout). Barrier methods in implementation classes throw throw BrokenBarrierException upon detection of breakage. Implementations may also support some means to clear this status.

await

int await()
          throws InterruptedException,
                 BrokenBarrierException

Enter barrier and wait for the other parties()-1 threads.

Returns:

the arrival index: the number of other parties that were still waiting upon entry. This is a unique value from zero to parties()-1. If it is zero, then the current thread was the last party to hit barrier point and so was responsible for releasing the others.

Throws:

BrokenBarrierException - if any other thread in any previous or current barrier since either creation or the last restart operation left the barrier prematurely due to interruption or time-out. (If so, the broken status is also set.) Threads that are notified to have been interrupted after being released are not considered to have broken the barrier. In all cases, the interruption status of the current thread is preserved, so can be tested by checking Thread.interrupted.

InterruptedException - if this thread was interrupted during the barrier, and was the one causing breakage. If so, broken status is also set.

await

int await(long msecs)
          throws InterruptedException,
                 TimeoutException,
                 BrokenBarrierException

Enter barrier and wait at most msecs for the other parties()-1 threads.

Returns:

if not timed out, the arrival index: the number of other parties that were still waiting upon entry. This is a unique value from zero to parties()-1. If it is zero, then the current thread was the last party to hit barrier point and so was responsible for releasing the others.

Throws:

BrokenBarrierException - if any other thread in any previous or current barrier since either creation or the last restart operation left the barrier prematurely due to interruption or time-out. (If so, the broken status is also set.) Threads that are noticed to have been interrupted after being released are not considered to have broken the barrier. In all cases, the interruption status of the current thread is preserved, so can be tested by checking Thread.interrupted.

InterruptedException - if this thread was interrupted during the barrier. If so, broken status is also set.

TimeoutException - if this thread timed out waiting for the barrier. If the timeout occured while already in the barrier, broken status is also set.

reset

void reset()

Reset to initial state. Clears both the broken status and any record of waiting threads, and releases all currently waiting threads with indeterminate return status. This method is intended only for use in recovery actions in which it is somehow known that no thread could possibly be relying on the the synchronization properties of this barrier.