monitor
Class Condition

java.lang.Object
  monitor.Condition

public class Condition
extends java.lang.Object

A condition queue.

Uses the signal and wait discipline (SW) or signal and leave (SL).

Each Condition object is associated with a single Assertion object and a single AbstractMonitor object. To construct a condition use the makeCondition methods from AbstractMonitor or Monitor

Threads can wait for the assertion represented by the Assertion object to become true by calling method await(). Threads can indicate that the assertion has become true by calling either method signal() (SW) or signalAndLeave() (SL). All these methods check the assertion and the monitor's invariant as appropriate.

Threads which wait on a Condition may supply a priority. In the absence of priority, waiting is fair -- in fact first-in last-out (FIFO).

Each of the await(), signal(), and signalAndLeave() methods have corresponding conditional versions, which first check the assertion before awaiting or signalling. These are: conditionalAwait(), conditionalSignal(), and conditionalSignalAndLeave().

Conditions also support a count accessor to determine the number of threads waiting on the condition.

Condition objects are intended to be used only by the thread which occupies the monitor which created them.

Version:

2.0

Author:

Theodore S. Norvell

See Also:

AbstractMonitor, Monitor, Assertion

Method Summary

void	await() Wait until a condition is signalled.
void	await(int priority) Just like await, but with a priority.
void	conditionalAwait() Wait only if the condition is not already true.
void	conditionalAwait(int priority) Just like conditionalAwait, but with a priority.
void	conditionalSignal() Signal this condition if its assertion is true and there is a waiting thread.
void	conditionalSignalAndLeave() Signal this condition if its assertion is true and there is a waiting thread; leave regardless.
<T> T	conditionalSignalAndLeave(T result) Signal this condition if its assertion is true and there is a waiting thread.
int	count() How many threads are waiting on this condition.
java.lang.String	getName()
boolean	isEmpty() Test if any thread is waiting on this condition.
void	signal() Signal this condition if there is a waiting thread.
void	signalAndLeave() Allows one thread which was waiting on the condition to reenter the monitor.
<T> T	signalAndLeave(T result) Signal if there is a waiting thread, then leave the monitor.

Methods inherited from class java.lang.Object

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

Method Detail

getName

public java.lang.String getName()

await

public void await(int priority)

Just like await, but with a priority. Threads awaiting with a lesser priority value are re-admitted to the monitor in preference to threads awaiting with a greater priority value. When priority values are the same, the order is FIFO.

Parameters:

priority - Lower value means more urgent.

Throws:

java.lang.AssertionError - if the current thread is not the occupant.

java.lang.AssertionError - if the invariant is not true to start

java.lang.AssertionError - if the assertion is not true on return

See Also:

await()

await

public void await()

Wait until a condition is signalled. The thread waits outside the monitor until the condition is signalled.

Precondition: Increasing the count by 1 must make the invariant true. This thread is in the monitor.

Postcondition: The assertion associated with this condition queue. This thread is in the monitor.

Note: threads are queued in a FIFO manner unless a priority is used; cond.await() is equivalent to cond.await( Integer.MAX_VALUE ).

Throws:

java.lang.AssertionError - if the current thread is not the occupant.

java.lang.AssertionError - if the invariant is not true to start

java.lang.AssertionError - if the assertion is not true on return

conditionalAwait

public void conditionalAwait()

Wait only if the condition is not already true.

Throws:

java.lang.AssertionError - if neither the invariant nor the assertion associated with this object is true

java.lang.AssertionError - if the current thread is not the occupant.

java.lang.AssertionError - if the assertion is not true on return

See Also:

await()

conditionalAwait

public void conditionalAwait(int priority)

Just like conditionalAwait, but with a priority.

Parameters:

priority - Lower value means more urgent.

Throws:

java.lang.AssertionError - if neither the invariant nor the assertion associated with this object is true

java.lang.AssertionError - if the current thread is not the occupant.

java.lang.AssertionError - if the assertion is not true on return

See Also:

conditionalAwait(), await( int priority )

signal

public void signal()

Signal this condition if there is a waiting thread.

Allows one thread that was waiting on the condition to reenter the monitor. Consequently the signalling thread waits outside. The signalling thread is allowed back into the monitor, once the monitor is again unoccupied. Threads which have signalled wait with a higher than normal priority and thus are allowed in ahead of other threads that are waiting to enter the monitor (e.g., those waiting in AbstractMonitor.enter()).

If there is no waiting thread, then this is a no-op, but the invariant is still checked, as it is a postcondition.

Preconditions:

• If isEmpty(), the monitor's invariant must be true.
• If not isEmpty(), then decreasing count() by 1 must make the proposition associated with this condition true.
• This thread is in the monitor.

Postcondition:

• The monitor's invariant.
• This thread is in the monitor.

Throws:

java.lang.AssertionError - if the current thread is not the occupant.

java.lang.AssertionError - if there is a waiting thread and the assertion is false (after decreasing the count by 1).

java.lang.AssertionError - if invariant is false on return.

signalAndLeave

public void signalAndLeave()

Allows one thread which was waiting on the condition to reenter the monitor. This thread (the one calling signalAndLeave) leaves the monitor immediately.

Preconditions:

• If isEmpty(), the monitor's invariant must be true.
• If not isEmpty(), then decreasing count() by 1 must make the proposition associated with this condition true.
• This thread is in the monitor.

Postcondition: This thread is not in the monitor.

Throws:

java.lang.AssertionError - if the current thread is not the occupant.

java.lang.AssertionError - if there is a waiting thread and the assertion is false (after decreasing the count by 1).

java.lang.AssertionError - if there is no waiting thread and the invariant is false.

See Also:

signal()

signalAndLeave

public <T> T signalAndLeave(T result)

Signal if there is a waiting thread, then leave the monitor. Allows one thread which was waiting on the condition to reenter the monitor. This thread (the one calling signalAndLeave) leaves the monitor immediately.

Preconditions:

• If isEmpty(), the monitor's invariant must be true.
• If not isEmpty(), then decreasing count() by 1 must make the proposition associated with this condition true.
• This thread is in the monitor.

Postcondition: This thread is not in the monitor.

Parameters:

result - A value to return.

Returns:

The value of the result parameter.

Throws:

java.lang.AssertionError - if the current thread is not the occupant.

java.lang.AssertionError - if there is a waiting thread and the assertion is false (after decreasing the count by 1).

java.lang.AssertionError - there is no waiting thread and the invariant is false.

conditionalSignal

public void conditionalSignal()

Signal this condition if its assertion is true and there is a waiting thread.

More precisely the condition is only signalled if its assertion would be true after the count is decreased by 1 and there is a waiting tread.

In such a case, the signalling thread waits outside. The signalling thread is allowed back into the monitor, once the monitor is again unoccupied. Threads which have signalled wait with a higher than normal priority and thus are allowed in ahead of other threads that are waiting to enter the monitor (e.g., those waiting in AbstractMonitor.enter()).

If the there are no awaiting threads, or the condition's assertion would not be true after the count were decreased by one, this method is essentially a no-op, although the invariant is still checked in such a case.

Preconditions:

• If isEmpty(), the monitor's invariant must be true.
• This thread is in the monitor.

Postcondition:

• The monitor's invariant.
• This thread is in the monitor.

Throws:

java.lang.AssertionError - if the current thread is not the occupant.

java.lang.AssertionError - if invariant is false on return.

See Also:

signal()

conditionalSignalAndLeave

public void conditionalSignalAndLeave()

Signal this condition if its assertion is true and there is a waiting thread; leave regardless.

More precisely the condition is only signalled if the assertion would be true after the count is decreased by 1 and there is a waiting thread.

This thread (the one calling signalAndLeave) leaves the monitor immediately.

Preconditions:

• If isEmpty() or the assertion would be false after decreasing the count by 1, the monitor's invariant must be true.
• This thread is in the monitor.

Postcondition:

• This thread is not in the monitor.

Throws:

java.lang.AssertionError - if the current thread is not the occupant.

java.lang.AssertionError - there is no waiting thread and the invariant is false.

java.lang.AssertionError - if there is a waiting thread and the assertion is false (after decreasing the count by 1) and the invariant is false.

See Also:

signalAndLeave(), conditionalSignal()

conditionalSignalAndLeave

public <T> T conditionalSignalAndLeave(T result)

Signal this condition if its assertion is true and there is a waiting thread. Leave regardless. More precisely the condition is only signalled if the assertion would be true after the count is decreased by 1.

This thread (the one calling signalAndLeave) leaves the monitor immediately.

Preconditions:

• If isEmpty() or the assertion would be false after decreasing the count by 1, the monitor's invariant must be true.
• This thread is in the monitor.

Postcondition:

• This thread is not in the monitor.

Parameters:

result - A value to be returned.

Returns:

The value of the result parameter.

Throws:

java.lang.AssertionError - if the current thread is not the occupant.

java.lang.AssertionError - there is no waiting thread and the invariant is false.

java.lang.AssertionError - if there is a waiting thread and the assertion is false (after decreasing the count by 1) and the invariant is false.

See Also:

conditionalSignalAndLeave()

isEmpty

public boolean isEmpty()

Test if any thread is waiting on this condition.

Returns:

count() == 0 .

Throws:

java.lang.AssertionError - if the current thread is not the occupant.

count

public int count()

How many threads are waiting on this condition.

Returns:

the number of Threads waiting on this condition.

Throws:

java.lang.AssertionError - if the current thread is not the occupant.