ProgramixGenericLib v5.0.1

com.programix.thread
Class Waiter

java.lang.Object
  extended by com.programix.thread.Waiter
All Implemented Interfaces:
ThreadSafe

public class Waiter
extends Object
implements ThreadSafe

Utility to assist in waiting for certain conditions to be met with and without timeouts. To specify an expression to be evaluated, see Waiter.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, ShutdownException, and InterruptException are all subclasses of RuntimeException so callers are not required to catch them.

Universal Behavior

InterruptException - 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. InterruptException is a subclass of RuntimeException and does not have to be caught by the caller. For a version that uses java.lang.InterruptedException instead, see WaiterIx.

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 Waiter.Condition
          Used to associate additional conditions on an existing Waiter.
static class Waiter.Expression
          Used to provide Waiter.Condition with a boolean expression to evaluate by subclassing and implementing the Waiter.Expression.isTrue() method.
 
Constructor Summary
Waiter(Object lock)
          Sets up a Waiter that's ready to have conditions created.
 
Method Summary
 Waiter.Condition createCondition(Waiter.Expression expr)
          Creates an Waiter.Condition for the specified Waiter.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

Waiter

public Waiter(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 Waiter.Condition createCondition(Waiter.Expression expr)
Creates an Waiter.Condition for the specified Waiter.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.


ProgramixGenericLib v5.0.1

Copyright © 2001-2009 Programix Incorporated. All rights reserved. ProgramixGenericLib is free and is OSI Certified Open Source Software under the BSD license.