net.grinder.script

Interface Barrier

public interface Barrier

Distributed synchronisation interface that allows worker threads to coordinate their actions.

A Barrier is created with a particular barrier name. A thread calls await() to wait for all other threads that have created a barrier with the same barrier name to also call await(). For each barrier name, The Grinder tracks the total number of barriers created N, and the number of barriers waiting W. Whenever the two numbers are equal, the calls to await() complete and the threads can continue.

Each cooperating thread should create its own Barrier instance using an agreed barrier name. Unlike the standard Java library's CyclicBarrier, only a single at any one time thread may call await on a Barrier instance. This class is thread safe; it may be useful cancel() a barrier from another thread.

Design note

This interface differs significantly from CyclicBarrier. This API supports a distributed implementation, where only a central coordinator knows the total number of instances. Communication between different nodes uses distributed events, rather than thread synchronisation primitives, and results in a more loosely coupled approach. The number of parties participating for a given barrier name can change dynamically. There is no concept of a broken barrier.

Since:

3.6

Author:

Philip Aston

Method Summary

Methods

Modifier and Type	Method and Description
void	await() Wait until all other barriers with the same name have invoked await().
boolean	await(long timeout) Equivalent to await(timeout, TimeUnit.MILLISECONDS).
boolean	await(long timeout, java.util.concurrent.TimeUnit unit) Version of await() that allows a timeout to be specified.
void	cancel() Cancel this Barrier and reduce the total number of instances for the barrier name.
java.lang.String	getName() Return the name of the barrier.

Method Detail

await

void await()
           throws GrinderException

Wait until all other barriers with the same name have invoked await().

If this barrier is not the last with the name to call await and has not been cancelled, this method blocks until one of the following happens:

• await is called for the last barrier.
• All non-waiting barriers with the same name are cancelled.
• This barrier is cancelled.
• Some other thread interrupts the current thread. In this case, the barrier instance will be cancelled.

If this barrier is the last with the name to call await, the method will not block. All await calls made by other threads for barriers with the same name will complete.

Throws:

CancelledBarrierException - If this barrier has been cancelled.

GrinderException - If the operation failed due to a network issue.

java.lang.IllegalStateException - If some other thread has called await on this barrier instance.

net.grinder.common.UncheckedInterruptedException - If the current thread is interrupted while waiting.

await

boolean await(long timeout,
            java.util.concurrent.TimeUnit unit)
              throws GrinderException

Version of await() that allows a timeout to be specified.

If the specified timeout elapses while the thread is waiting, the method will return false, and the barrier instance will be cancelled.

Parameters:

timeout - The time to wait for the barrier.

unit - The time unit of the timeout parameter.

Returns:

false if and only if the waiting time detectably elapsed before return from the method.

Throws:

CancelledBarrierException - If this barrier has been cancelled.

java.lang.IllegalStateException - If some other thread has called await on this barrier instance.

GrinderException - If the operation failed due to a network issue.

net.grinder.common.UncheckedInterruptedException - If the current thread is interrupted while waiting.

await

boolean await(long timeout)
              throws GrinderException

Equivalent to await(timeout, TimeUnit.MILLISECONDS).

Parameters:

timeout - The time to wait for the barrier.

Returns:

false if and only if the waiting time detectably elapsed before return from the method.

Throws:

CancelledBarrierException - If this barrier has been cancelled.

java.lang.IllegalStateException - If some other thread has called await on this barrier instance.

GrinderException - If the operation failed for some other reason.

net.grinder.common.UncheckedInterruptedException - If the current thread is interrupted while waiting.

cancel

void cancel()
            throws GrinderException

Cancel this Barrier and reduce the total number of instances for the barrier name. If another thread is waiting on this barrier instance, it will receive a CancelledBarrierException. Otherwise, if this was the only idle barrier, the others with the same name will be awoken.

Subsequent calls to await() for this Barrier will result in an CancelledBarrierException.

Throws:

GrinderException - If the operation failed due to a network issue.

getName

java.lang.String getName()

Return the name of the barrier.

Returns:

The barrier name.