com.programix.thread.ix
Class WaiterIx

java.lang.Object
  com.programix.thread.ix.WaiterIx

All Implemented Interfaces:

ThreadSafe

public class WaiterIx
extends Object
implements ThreadSafe

This class uses java.lang.InterruptedException (checked exception) instead of the InterruptException (unchecked "runtime" exception). See Waiter for the runtime exception version.

Utility to assist in waiting for certain conditions to be met with and without timeouts. To specify an expression to be evaluated, see WaiterIx.Expression.

Waiter also handles the potential for a shutdown by throwing ShutdownException from most methods.

TimedOutException is thrown by some methods to indicate that a timeout occurred. Some other methods may simple return ThreadTools.TIMED_OUT (false) to indicate a timeout.

TimedOutException and ShutdownException are both subclasses of RuntimeException so callers are not required to catch them. This class does throws java.lang.InterruptedException when interrupts occur (unlike Waiter which throws the runtime exception InterruptException).

Universal Behavior

InterruptedException - thrown from methods when the calling thread is interrupted while waiting inside the method. This exception is only thrown if any waiting is necessary; if the condition has already been met, the calling thread doesn't need to wait and will not notice if it has been interrupted or not. InterruptedException is a subclass of Exception and has to be caught by the caller. For a version that uses InterruptException instead, see Waiter.

ShutdownException - thrown from methods when this WaitFor has been shutdown via shutdown. If the shutdown occurs before a method is called, then the method immediately throws a ShutdownException (without evaluating anything else). If the shutdown occurs while the calling thread is waiting inside a method, then the waiting ends and the method throws a ShutdownException (without evaluating anything else). ShutdownException is a subclass of RuntimeException and does not have to be caught by the caller.

msTimeout - the maximum number of milliseconds to wait for a condition to be met. On occasion, the actual waiting time may be slightly longer due to lock contention and CPU scheduling. When the calling thread runs out of time, it competes to reacquire the lock, and the condition is evaluated once again. If the condition has finally been met (without any regard to how much time may have elapsed), then the calling thread leaves the method indicating 'success' (the condition has been met@mdash;even if a few milliseconds too late). If ThreadTools.NO_TIMEOUT (0L) is passed in for msTimeout, then waiting will continue without regard for how much time has elapsed (waiting will never timeout). If a negative timeout is passed in, then no waiting will occur; the condition will just be evaluated immediately. If the condition has already been met, then the calling thread leaves the method indicating 'success' (the condition has been met—even if the timeout value is silly). If the condition has not been met, then this 'negative timeout' situation is treated as a timeout).

ThreadTools.SUCCESS and ThreadTools.TIMED_OUT - are used as return values by waitWhileX and wailUntilY methods that take a timeout value (msTimeout). ThreadTools.SUCCESS (true) is returned if the condition was already met at the time of invocation or was met after some waiting some waiting (and is still being met while the lock is held). ThreadTools.TIMED_OUT (false) is returned if the specified time (msTimeout) elapses and the condition is still not met (or if a negative timeout value was passed in and the condition was not already met).

TimedOutException - can be thrown by waitWhileX and wailUntilY methods that take a timeout value (msTimeout) and do not use a return value to indicate timeout (these methods declare that they might throw a TimedOutException). TimedOutException is thrown if the condition has not been met within the time limit specified by msTimeout. TimedOutException is a subclass of RuntimeException and does not have to be caught by the caller.

For advanced tools and utilities related to multithreading, please check out JThreadKit.

Author:

Paul Hyde

Nested Class Summary

class	WaiterIx.Condition Used to associate additional conditions on an existing WaiterIx.
static class	WaiterIx.Expression Used to provide WaiterIx.Condition with a boolean expression to evaluate by subclassing and implementing the WaiterIx.Expression.isTrue() method.

Constructor Summary

WaiterIx(Object lock)
Sets up a Waiter that's ready to have conditions created.

Method Summary

WaiterIx.Condition	createCondition(WaiterIx.Expression expr) Creates an WaiterIx.Condition for the specified WaiterIx.Expression that is tightly associated with this Waiter.
Object	getLockObject() Returns the reference to the object that is being used to lock on by all the internal synchronized's and wait and notifyAll methods.
boolean	isShutdown() Returns true if any thread has previously called shutdown.
void	shutdown() Immediately shuts down this Waiter.
void	shutdownCheck() Immediately throws a ShutdownException if any thread has previously called shutdown.
void	signalChange() Called to signal to any and all waiting threads (on the lock object specified at construction) that something has changed.

Methods inherited from class java.lang.Object

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

Constructor Detail

WaiterIx

public WaiterIx(Object lock)

Sets up a Waiter that's ready to have conditions created.

Parameters:

lock - the object to synchronize on for safe multithreaded access and the object to use for wait and notifyAll signaling.

Method Detail

createCondition

public WaiterIx.Condition createCondition(WaiterIx.Expression expr)

Creates an WaiterIx.Condition for the specified WaiterIx.Expression that is tightly associated with this Waiter. All WaitFor.Condition's lock on the same object, hear about a change via signalChange(), and throw ShutdownException when (or if) this Waiter is shutdown.

signalChange

public void signalChange()

Called to signal to any and all waiting threads (on the lock object specified at construction) that something has changed. Internally, notifyAll is used.

shutdown

public void shutdown()

Immediately shuts down this Waiter. Any threads that are waiting inside waitUntilX and waitWhileY methods will throw a ShutdownException from the method. Any future calls to most of the methods on this class will result in a Shutdown exception being immediately thrown (any of the methods on this class that declare that they might throw a ShutdownException fall into this category).

This method may be harmlessly called multiple times.

isShutdown

public boolean isShutdown()

Returns true if any thread has previously called shutdown.

shutdownCheck

public void shutdownCheck()
                   throws ShutdownException

Immediately throws a ShutdownException if any thread has previously called shutdown.

Throws:

ShutdownException

getLockObject

public Object getLockObject()

Returns the reference to the object that is being used to lock on by all the internal synchronized's and wait and notifyAll methods.