edu.rice.cs.plt.concurrent
Class StateMonitor<T>

java.lang.Object
  edu.rice.cs.plt.concurrent.StateMonitor<T>

All Implemented Interfaces:

Box<T>, Thunk<T>, Serializable

public class StateMonitor<T>
extends Object
implements Box<T>, Serializable

Provides a convenient facility for blocking until a state change explicitly occurs. Each time the wrapped state value changes, the blocked threads check to see if the new state meets a provided criteria.

Ideally, this class would extend ConcurrentBox. Unfortunately, the methods of AtomicReference are final, and so they can't be overridden here. Also, since locking is necessary when performing thread notification, these implementations simply use locking, rather than relying on built-in non-blocking atomic primitives.

See Also:

Serialized Form

Constructor Summary

StateMonitor(T state)

Method Summary

T	attemptEnsureNotState(T wrong) Tries to ensure that the state does not equal wrong before continuing.
T	attemptEnsureNotState(T expected, long timeout) Tries to ensure that the state does not equal wrong before continuing.
T	attemptEnsureNotState(T expected, long timeout, TimeUnit unit) Tries to ensure that the state does not equal wrong before continuing.
T	attemptEnsurePredicate(Predicate<? super T> predicate) Tries to ensure that predicate accepts the current state before continuing.
T	attemptEnsurePredicate(Predicate<? super T> predicate, long timeout) Tries to ensure that predicate accepts the current state before continuing.
T	attemptEnsurePredicate(Predicate<? super T> predicate, long timeout, TimeUnit unit) Tries to ensure that predicate accepts the current state before continuing.
T	attemptEnsureState(T expected) Tries to ensure that the state equals expected before continuing.
T	attemptEnsureState(T expected, long timeout) Tries to ensure that the state equals expected before continuing.
T	attemptEnsureState(T expected, long timeout, TimeUnit unit) Tries to ensure that the monitor has been signaled before continuing.
boolean	compareAndSet(T expect, T update) If the current state is expect, change it to update.
T	ensureNotState(T wrong) Ensures that the state does not equal wrong before continuing.
T	ensureNotState(T wrong, long timeout) Ensures that the state does not equal wrong before continuing.
T	ensureNotState(T wrong, long timeout, TimeUnit unit) Ensures that the state does not equal wrong before continuing.
T	ensurePredicate(Predicate<? super T> predicate) Ensures that predicate accepts the current state before continuing.
T	ensurePredicate(Predicate<? super T> predicate, long timeout) Ensures that predicate accepts the current state before continuing.
T	ensurePredicate(Predicate<? super T> predicate, long timeout, TimeUnit unit) Ensures that predicate accepts the current state before continuing.
T	ensureState(T expected) Ensures that the state equals expected before continuing.
T	ensureState(T expected, long timeout) Ensures that the state equals expected before continuing.
T	ensureState(T expected, long timeout, TimeUnit unit) Ensures that the state equals expected before continuing.
T	getAndSet(T newState) Change the state to newState; return the previous state.
void	set(T newState) Change the state to newState.
T	value() Get the current state.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

StateMonitor

public StateMonitor(T state)

Method Detail

value

public T value()

Get the current state. (No guarantee is made about how long this value is valid — a concurrent state change may occur immediately.)

Specified by:

value in interface Thunk<T>

set

public void set(T newState)

Change the state to newState.

Specified by:

set in interface Box<T>

getAndSet

public T getAndSet(T newState)

Change the state to newState; return the previous state.

See Also:

AtomicReference.getAndSet(V)

compareAndSet

public boolean compareAndSet(T expect,
                             T update)

If the current state is expect, change it to update. In this case, true is returned. Otherwise, give up and return false.

See Also:

AtomicReference.compareAndSet(V, V)

ensureState

public T ensureState(T expected)
              throws InterruptedException

Ensures that the state equals expected before continuing. Blocks if necessary.

Returns:

The state at the time this method returns (always equal to expected).

Throws:

InterruptedException

ensureState

public T ensureState(T expected,
                     long timeout)
              throws InterruptedException,
                     TimeoutException

Ensures that the state equals expected before continuing. Blocks if necessary; fails if the the timeout is reached.

Parameters:

timeout - Maximum wait time, in milliseconds.

Returns:

The state at the time this method returns (always equal to expected).

Throws:

InterruptedException

TimeoutException

ensureState

public T ensureState(T expected,
                     long timeout,
                     TimeUnit unit)
              throws InterruptedException,
                     TimeoutException

Ensures that the state equals expected before continuing. Blocks if necessary; fails if the the timeout is reached.

Parameters:

timeout - Maximum wait time, in unit units.

unit - Units for timeout.

Returns:

The state at the time this method returns (always equal to expected).

Throws:

InterruptedException

TimeoutException

attemptEnsureState

public T attemptEnsureState(T expected)

Tries to ensure that the state equals expected before continuing. Blocks if necessary. Stops waiting if interrupted.

Returns:

The state at the time this method returns (if not interrupted, this is equal to expected).

attemptEnsureState

public T attemptEnsureState(T expected,
                            long timeout)

Tries to ensure that the state equals expected before continuing. Blocks if necessary. If interrupted or if the timeout is reached, stops waiting.

Parameters:

timeout - Maximum wait time, in milliseconds.

Returns:

The state at the time this method returns (barring an interrupt or timeout, this is equal to expected).

attemptEnsureState

public T attemptEnsureState(T expected,
                            long timeout,
                            TimeUnit unit)

Tries to ensure that the monitor has been signaled before continuing. Blocks if necessary. If interrupted or if the timeout is reached, stops waiting.

Parameters:

timeout - Maximum wait time, in unit units.

unit - Units for timeout.

Returns:

The state at the time this method returns (barring an interrupt or timeout, this is equal to expected).

ensureNotState

public T ensureNotState(T wrong)
                 throws InterruptedException

Ensures that the state does not equal wrong before continuing. Blocks if necessary.

Returns:

The state at the time this method returns (never equal to wrong).

Throws:

InterruptedException

ensureNotState

public T ensureNotState(T wrong,
                        long timeout)
                 throws InterruptedException,
                        TimeoutException

Ensures that the state does not equal wrong before continuing. Blocks if necessary; fails if the the timeout is reached.

Parameters:

timeout - Maximum wait time, in milliseconds.

Returns:

The state at the time this method returns (always equal to expected).

Throws:

InterruptedException

TimeoutException

ensureNotState

public T ensureNotState(T wrong,
                        long timeout,
                        TimeUnit unit)
                 throws InterruptedException,
                        TimeoutException

Ensures that the state does not equal wrong before continuing. Blocks if necessary; fails if the the timeout is reached.

Parameters:

timeout - Maximum wait time, in unit units.

unit - Units for timeout.

Returns:

The state at the time this method returns (always equal to expected).

Throws:

InterruptedException

TimeoutException

attemptEnsureNotState

public T attemptEnsureNotState(T wrong)

Tries to ensure that the state does not equal wrong before continuing. Blocks if necessary. Stops waiting if interrupted.

Returns:

The state at the time this method returns (if not interrupted, this is not equal to wrong).

attemptEnsureNotState

public T attemptEnsureNotState(T expected,
                               long timeout)

Tries to ensure that the state does not equal wrong before continuing. Blocks if necessary. If the wait is interrupted or the timeout is reached, stops waiting.

Parameters:

timeout - Maximum wait time, in milliseconds.

Returns:

The state at the time this method returns (barring an interrupt or timeout, this is not equal to wrong).

attemptEnsureNotState

public T attemptEnsureNotState(T expected,
                               long timeout,
                               TimeUnit unit)

Tries to ensure that the state does not equal wrong before continuing. Blocks if necessary. If the wait is interrupted or the timeout is reached, stops waiting.

Parameters:

timeout - Maximum wait time, in unit units.

unit - Units for timeout.

Returns:

The state at the time this method returns (barring an interrupt or timeout, this is not equal to wrong).

ensurePredicate

public T ensurePredicate(Predicate<? super T> predicate)
                  throws InterruptedException

Ensures that predicate accepts the current state before continuing. Blocks if necessary.

Returns:

The state at the time this method returns (always a state accepted by predicate).

Throws:

InterruptedException

ensurePredicate

public T ensurePredicate(Predicate<? super T> predicate,
                         long timeout)
                  throws InterruptedException,
                         TimeoutException

Ensures that predicate accepts the current state before continuing. Blocks if necessary; fails if the the timeout is reached.

Parameters:

timeout - Maximum wait time, in milliseconds.

Returns:

The state at the time this method returns (always a state accepted by predicate).

Throws:

InterruptedException

TimeoutException

ensurePredicate

public T ensurePredicate(Predicate<? super T> predicate,
                         long timeout,
                         TimeUnit unit)
                  throws InterruptedException,
                         TimeoutException

Ensures that predicate accepts the current state before continuing. Blocks if necessary; fails if the the timeout is reached.

Parameters:

timeout - Maximum wait time, in unit units.

unit - Units for timeout.

Returns:

The state at the time this method returns (always a state accepted by predicate).

Throws:

InterruptedException

TimeoutException

attemptEnsurePredicate

public T attemptEnsurePredicate(Predicate<? super T> predicate)

Tries to ensure that predicate accepts the current state before continuing. Blocks if necessary. Stops waiting if interrupted.

Returns:

The state at the time this method returns (if not interrupted, this was accepted by predicate).

attemptEnsurePredicate

public T attemptEnsurePredicate(Predicate<? super T> predicate,
                                long timeout)

Tries to ensure that predicate accepts the current state before continuing. Blocks if necessary. If the wait is interrupted or the timeout is reached, stops waiting.

Parameters:

timeout - Maximum wait time, in milliseconds.

Returns:

The state at the time this method returns (barring an interrupt or timeout, this was accepted by predicate).

attemptEnsurePredicate

public T attemptEnsurePredicate(Predicate<? super T> predicate,
                                long timeout,
                                TimeUnit unit)

Tries to ensure that predicate accepts the current state before continuing. Blocks if necessary. If the wait is interrupted or the timeout is reached, stops waiting.

Parameters:

timeout - Maximum wait time, in unit units.

unit - Units for timeout.

Returns:

The state at the time this method returns (barring an interrupt or timeout, this was accepted by predicate).