net.grinder.synchronisation

Interface BarrierGroup

All Known Implementing Classes:

AbstractBarrierGroups.BarrierGroupImplementation

public interface BarrierGroup

A barrier group.

A group has a number of barriers, N, and a number of waiters, W. At any time, 0 <= W < N or 0 == W == N.

One or more listeners can be registered with the group.

Whenever N is positive and becomes equal to W, W will be reset to 0 and all the listeners will be notified.

If removeBarriers(long) reduces N to 0, the instance will become invalid. This allows implementations to remove barrier groups that are no longer in use.

This interface tracks the identity of waiting barriers through BarrierIdentity. Doing so allows communication with the Barrier API to be asynchronous.

Author:

Philip Aston

See Also:

Barrier

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	BarrierGroup.Listener Callback used to notify listeners.

Method Summary

Methods

Modifier and Type	Method and Description
void	addBarrier() Increase the number of barriers in the group.
void	addListener(BarrierGroup.Listener listener) Add a listener.
void	addWaiter(BarrierIdentity barrierIdentity) Add a waiter.
void	cancelAll() Cancels all waiters and removes all barriers.
void	cancelWaiter(BarrierIdentity barrierIdentity) Cancel a waiter.
String	getName() Return the name of the barrier group.
void	removeBarriers(long n) Decrease the number of barriers in the group.
void	removeListener(BarrierGroup.Listener listener) Remove a listener.

Method Detail

addListener

void addListener(BarrierGroup.Listener listener)

Add a listener.

Parameters:

listener - The listener.

removeListener

void removeListener(BarrierGroup.Listener listener)

Remove a listener.

Parameters:

listener - The listener.

addBarrier

void addBarrier()
                throws CommunicationException

Increase the number of barriers in the group.

Throws:

CommunicationException - If the operation could not be completed due to a network communication problem. The barrier group is left in an unknown state.

IllegalStateException - If the barrier group is invalid. A group becomes invalid if removeBarriers(long) removes all of the barriers.

removeBarriers

void removeBarriers(long n)
                    throws CommunicationException

Decrease the number of barriers in the group.

Parameters:

n - The number of barriers to remove.

Throws:

CommunicationException - If the operation could not be completed due to a network communication problem. The barrier group is left in an unknown state.

IllegalStateException - If n > N - W.

addWaiter

void addWaiter(BarrierIdentity barrierIdentity)
               throws CommunicationException

Add a waiter.

Parameters:

barrierIdentity - Identifies the barrier.

Throws:

CommunicationException - If the operation could not be completed due to a network communication problem. The barrier group is left in an unknown state.

IllegalStateException - If N == 0, or the group is invalid.

cancelWaiter

void cancelWaiter(BarrierIdentity barrierIdentity)
                  throws CommunicationException

Cancel a waiter.

Does nothing if the barrierIdentity refers to an unknown waiter. This copes with the following cases:

• Cancel received asynchronously after barrier has been triggered.
• Cancel received without a call to addWaiter(net.grinder.synchronisation.messages.BarrierIdentity).

Parameters:

barrierIdentity - Identifies the barrier.

Throws:

CommunicationException - If the operation could not be completed due to a network communication problem. The barrier group is left in an unknown state.

cancelAll

void cancelAll()
               throws CommunicationException

Cancels all waiters and removes all barriers.

Throws:

CommunicationException - If the operation could not be completed due to a network communication problem. The barrier group is left in an unknown state.

getName

String getName()

Return the name of the barrier group.

Returns:

The barrier group name.