com.jthreadkit
Class SyncInteger

java.lang.Object
  |
  +--com.jthreadkit.SyncInteger

All Implemented Interfaces:

AccessibleLock, SimpleShutdown, TimedOutExceptionOption

public class SyncInteger

extends Object

implements AccessibleLock, SimpleShutdown, TimedOutExceptionOption

SyncInteger is used to signal int values among two or more threads. SyncInteger encapsulates Java's wait-notify mechanism making it simple and safe for one thread to wait for a certain value to be set by another thread. In fact, any number of threads can be waiting and any number of threads can safely change the value.

For example, let's say that the value is currently 2 and threadA comes along and waits until the value is in the inclusive range of 5 to 8. Meanwhile sometime soon after threadA starts waiting, threadB comes along and sets the value to be 7, then threadA stops waiting and proceeds. Specifically, if there's an instance of SyncInteger constructed:

SyncInteger si = new SyncInteger(2);

and threadA executes this code:

try { si.waitUntilValueInRange(5, 8); //... } catch ( InterruptedException x ) { //...

and then a little while later threadB executes this code:

si.setValue(7);

At this point, threadA returns from waitUntilValueInRange(5, 8) and continues on. If threadA calls waitUntilValueInRange(5, 8) and the value is already at least 5 and at most 8, it returns right away with no delay.

InterruptedException - can be thrown from many of the methods in this class. If one thread is blocked inside one of these methods and another thread interrupts it, InterruptedException is thrown by the blocked thread.

TimedOutException - can be thrown from many of the methods in this class only if the "use TimedOutException" option is set. If true is passed to the setUseTimedOutException() method, the option is set and TimedOutException will be thrown from methods that timeout when the specified timeout period expires. If false is passed, the option is unset and TimedOutException will never be thrown. The isUseTimedOutExceptionSet() method returns true if the option is set and TimedOutException's will be thrown. TimedOutException is a subclass of RuntimeException so there is no need for a try-catch block if the option is not set. This option allows you to determine whether or not a timeout is an exceptional condition in your context (a condition that should result in an exception being thrown). If timeouts are routine, you probably will want to leave this option in its default unset state. See the class description of TimedOutException for more information.

ShutdownException - can be thrown from many of the methods in this class. This exception is not thrown by methods until the shutdown() method is called. If shutdown() is never called, this exception will never be thrown and can be safely ignored. ShutdownException is a subclass of RuntimeException so there is no need for a try-catch block if shutdown() won't be called. After shutdown() is called, any threads that are currently blocked waiting will immediately throw this exception. In addition, any future calls to methods that would either result in waiting or would alter the object cause this exception to be thrown (if no waiting is needed because the condition is already met, this exception will not be thrown). See the class description of ShutdownException for more information.

Constructor Summary

SyncInteger()

SyncInteger(int initialValue)

SyncInteger(int initialValue, int minValue, int maxValue)

SyncInteger(int initialValue, int minValue, int maxValue, Object lock, boolean useTimedOutException)
Creates an instance specifying all parameters.

SyncInteger(int initialValue, Object lock)

SyncInteger(int initialValue, Object lock, boolean useTimedOutException)

Method Summary

int	decreaseValueBy(int decrement) Decrements the current value by the specified amount and returns the resulting new value.
Object	getLockObject() Returns the reference to the object that is synchronized on by other methods in the implementing class.
int	getMaxValue()
int	getMinValue()
int	getValue()
int	increaseValueBy(int increment) Increments the current value by the specified amount and returns the resulting new value.
boolean	isMaxValue()
boolean	isMinValue()
boolean	isUseTimedOutExceptionSet() Used to determine whether or not TimedOutException will be thrown by methods when timout periods expire.
boolean	isZero()
void	setMaxValue(int newMaxValue)
void	setMinValue(int newMinValue)
void	setUseTimedOutException(boolean useException) Used to change the timeout behavior of methods on the implementing classes.
void	setValue(int newValue)
void	setValueRange(int newMinValue, int newMaxValue)
void	shutdown() A full shutdown is immediately initiated resulting in a ShutdownException being thrown by any methods that modify the object or wait for it to be modified.
String	toString()
void	waitForValueToChange()
boolean	waitForValueToChange(long msTimeout)
void	waitForValueToClimbTo(int atLeast)
boolean	waitForValueToClimbTo(int atLeast, long msTimeout)
void	waitForValueToFallTo(int atMost)
boolean	waitForValueToFallTo(int atMost, long msTimeout)
void	waitUntilMaxValue()
boolean	waitUntilMaxValue(long msTimeout)
void	waitUntilMinValue()
boolean	waitUntilMinValue(long msTimeout)
void	waitUntilValueInRange(int min, int max)
boolean	waitUntilValueInRange(int min, int max, long msTimeout)
void	waitUntilValueIs(int val)
boolean	waitUntilValueIs(int val, long msTimeout)
void	waitUntilZero()
boolean	waitUntilZero(long msTimeout)
void	waitWhileMaxValue()
boolean	waitWhileMaxValue(long msTimeout)
void	waitWhileMinValue()
boolean	waitWhileMinValue(long msTimeout)
void	waitWhileValueInRange(int min, int max)
boolean	waitWhileValueInRange(int min, int max, long msTimeout)
void	waitWhileValueIs(int val)
boolean	waitWhileValueIs(int val, long msTimeout)
void	waitWhileZero()
boolean	waitWhileZero(long msTimeout)

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

SyncInteger

public SyncInteger(int initialValue,
                   int minValue,
                   int maxValue,
                   Object lock,
                   boolean useTimedOutException)
            throws IllegalArgumentException

Creates an instance specifying all parameters.

Parameters:

initialValue - the value to start off with.

minValue - the lowest value permitted.

maxValue - the highest value permitted.

lock - an alternate object to synchronize on. If null, synchronization is on this instance of SyncInteger. See AccessibleLock.

useTimedOutException - if true a TimedOutException will be thrown when method calls timeout. If false, the timeout is indicated by the return value. See TimedOutExceptionOption.

SyncInteger

public SyncInteger(int initialValue,
                   int minValue,
                   int maxValue)
            throws IllegalArgumentException

SyncInteger

public SyncInteger(int initialValue,
                   Object lock,
                   boolean useTimedOutException)

SyncInteger

public SyncInteger(int initialValue,
                   Object lock)

SyncInteger

public SyncInteger(int initialValue)

SyncInteger

public SyncInteger()

Method Detail

getLockObject

public Object getLockObject()

Description copied from interface: AccessibleLock

Returns the reference to the object that is synchronized on by other methods in the implementing class. This reference is not permitted to change after construction, so this method can be called once and the reference saved.

This reference can be used in synchronized blocks to keep other threads from sneaking in between methods calls like this:

obj = //... synchronized ( obj.getLockObject() ) { obj.methodA(); obj.methodB(); }

Specified by:

getLockObject in interface AccessibleLock

Following copied from interface: com.jthreadkit.AccessibleLock

Returns:

the object used to lock on to control concurrent access.

setUseTimedOutException

public void setUseTimedOutException(boolean useException)
                             throws ShutdownException

Description copied from interface: TimedOutExceptionOption

Used to change the timeout behavior of methods on the implementing classes. If this option is set to true methods will throw a TimedOutException when the specified timeout period expires. If this option is not set, methods usually signal a timeout through a return value. Use isUseTimedOutExceptionSet() to check the current setting.

Specified by:

setUseTimedOutException in interface TimedOutExceptionOption

Following copied from interface: com.jthreadkit.TimedOutExceptionOption

Parameters:

useException - if true is passed then TimedOutException will be thrown after timeouts, if false is passed, timeouts do not result in exceptions.

Throws:

ShutdownException - if this object has already been shutdown.

isUseTimedOutExceptionSet

public boolean isUseTimedOutExceptionSet()

Description copied from interface: TimedOutExceptionOption

Used to determine whether or not TimedOutException will be thrown by methods when timout periods expire. The setUseTimedOutException() method is used to change this setting.

Specified by:

isUseTimedOutExceptionSet in interface TimedOutExceptionOption

Following copied from interface: com.jthreadkit.TimedOutExceptionOption

Returns:

true if timeouts will result in exceptions being thrown, false otherwise.

shutdown

public void shutdown()

Description copied from interface: SimpleShutdown

A full shutdown is immediately initiated resulting in a ShutdownException being thrown by any methods that modify the object or wait for it to be modified. See this explanation for more.

Specified by:

shutdown in interface SimpleShutdown

getValue

public int getValue()

setValue

public void setValue(int newValue)
              throws IllegalArgumentException,
                     ShutdownException

increaseValueBy

public int increaseValueBy(int increment)
                    throws IllegalArgumentException,
                           ShutdownException

Increments the current value by the specified amount and returns the resulting new value.

decreaseValueBy

public int decreaseValueBy(int decrement)
                    throws IllegalArgumentException,
                           ShutdownException

Decrements the current value by the specified amount and returns the resulting new value.

setMinValue

public void setMinValue(int newMinValue)
                 throws IllegalArgumentException,
                        ShutdownException

getMinValue

public int getMinValue()

setMaxValue

public void setMaxValue(int newMaxValue)
                 throws IllegalArgumentException,
                        ShutdownException

getMaxValue

public int getMaxValue()

setValueRange

public void setValueRange(int newMinValue,
                          int newMaxValue)
                   throws IllegalArgumentException,
                          ShutdownException

isMinValue

public boolean isMinValue()

isMaxValue

public boolean isMaxValue()

isZero

public boolean isZero()

waitUntilValueInRange

public boolean waitUntilValueInRange(int min,
                                     int max,
                                     long msTimeout)
                              throws InterruptedException,
                                     TimedOutException,
                                     ShutdownException,
                                     IllegalArgumentException

waitUntilValueInRange

public void waitUntilValueInRange(int min,
                                  int max)
                           throws InterruptedException,
                                  ShutdownException,
                                  IllegalArgumentException

waitWhileValueInRange

public boolean waitWhileValueInRange(int min,
                                     int max,
                                     long msTimeout)
                              throws InterruptedException,
                                     TimedOutException,
                                     ShutdownException,
                                     IllegalArgumentException

waitWhileValueInRange

public void waitWhileValueInRange(int min,
                                  int max)
                           throws InterruptedException,
                                  ShutdownException,
                                  IllegalArgumentException

waitForValueToChange

public boolean waitForValueToChange(long msTimeout)
                             throws InterruptedException,
                                    TimedOutException,
                                    ShutdownException

waitForValueToChange

public void waitForValueToChange()
                          throws InterruptedException,
                                 ShutdownException

waitForValueToFallTo

public boolean waitForValueToFallTo(int atMost,
                                    long msTimeout)
                             throws InterruptedException,
                                    TimedOutException,
                                    ShutdownException

waitForValueToFallTo

public void waitForValueToFallTo(int atMost)
                          throws InterruptedException,
                                 ShutdownException

waitForValueToClimbTo

public boolean waitForValueToClimbTo(int atLeast,
                                     long msTimeout)
                              throws InterruptedException,
                                     TimedOutException,
                                     ShutdownException

waitForValueToClimbTo

public void waitForValueToClimbTo(int atLeast)
                           throws InterruptedException,
                                  ShutdownException

waitWhileZero

public boolean waitWhileZero(long msTimeout)
                      throws InterruptedException,
                             TimedOutException,
                             ShutdownException

waitWhileZero

public void waitWhileZero()
                   throws InterruptedException,
                          ShutdownException

waitUntilZero

public boolean waitUntilZero(long msTimeout)
                      throws InterruptedException,
                             TimedOutException,
                             ShutdownException

waitUntilZero

public void waitUntilZero()
                   throws InterruptedException,
                          ShutdownException

waitWhileValueIs

public boolean waitWhileValueIs(int val,
                                long msTimeout)
                         throws InterruptedException,
                                TimedOutException,
                                ShutdownException

waitWhileValueIs

public void waitWhileValueIs(int val)
                      throws InterruptedException,
                             ShutdownException

waitUntilValueIs

public boolean waitUntilValueIs(int val,
                                long msTimeout)
                         throws InterruptedException,
                                TimedOutException,
                                ShutdownException

waitUntilValueIs

public void waitUntilValueIs(int val)
                      throws InterruptedException,
                             ShutdownException

waitWhileMaxValue

public boolean waitWhileMaxValue(long msTimeout)
                          throws InterruptedException,
                                 TimedOutException,
                                 ShutdownException

waitWhileMaxValue

public void waitWhileMaxValue()
                       throws InterruptedException,
                              ShutdownException

waitUntilMaxValue

public boolean waitUntilMaxValue(long msTimeout)
                          throws InterruptedException,
                                 TimedOutException,
                                 ShutdownException

waitUntilMaxValue

public void waitUntilMaxValue()
                       throws InterruptedException,
                              ShutdownException

waitWhileMinValue

public boolean waitWhileMinValue(long msTimeout)
                          throws InterruptedException,
                                 TimedOutException,
                                 ShutdownException

waitWhileMinValue

public void waitWhileMinValue()
                       throws InterruptedException,
                              ShutdownException

waitUntilMinValue

public boolean waitUntilMinValue(long msTimeout)
                          throws InterruptedException,
                                 TimedOutException,
                                 ShutdownException

waitUntilMinValue

public void waitUntilMinValue()
                       throws InterruptedException,
                              ShutdownException

toString

public String toString()

Overrides:

toString in class Object