com.jthreadkit
Class SyncBoolean

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

All Implemented Interfaces:

AccessibleLock, SimpleShutdown, TimedOutExceptionOption

public class SyncBoolean

extends Object

implements AccessibleLock, SimpleShutdown, TimedOutExceptionOption

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

For example, threadA waits until the value is true. Meanwhile sometime soon threadB comes along and sets the value to be true, then threadA proceeds. Specifically, if there's an instance of SyncBoolean constructed:

SyncBoolean sb = new SyncBoolean(false);

and threadA executes this code:

try { sb.waitUntilTrue(); //... } catch ( InterruptedException x ) { //...

and then a little while later threadB executes this code:

sb.setValue(true);

At this point, threadA returns from waitUntilTrue() and continues on. If threadA calls waitUntilTrue() and the value is already true, it returns right away with no delay.

SyncBoolean can also be used as a mutex to control concurrent access to a block of code instead of using synchronized. The advantage is that threads waiting to get into the protected block can use a timeout to limit their wait and/or they respond to an interrupt by throwing an InterruptedException (threads blocked waiting to get into a synchronized block do not respond to interrupts - see Java Thread Programming for more on interrupts and synchronization). This can be done with an instance of SyncBoolean referenced by sb:

// When false, the lock is free to use, wait for it... sb.waitToSetTrue(); try { // exclusive access... // ... } finally { // No matter how the try block goes, be // sure to release the lock on the way out. sb.setValue(false); }

Note that initially, sb must be false and that when any thread is in the try block, sb is true.

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

SyncBoolean()
Builds an instance with an initial value of false.

SyncBoolean(boolean initialValue)
Builds an instance with the specified initial value.

SyncBoolean(boolean initialValue, Object lock, boolean useTimedOutException)
Builds an instance with the specified initial value.

Method Summary

Object	getLockObject() Returns the reference to the object that is synchronized on by other methods in the implementing class.
boolean	ifFalseSetTrue() If the value is currently false, it is changed to be true.
boolean	ifTrueSetFalse() If the value is currently true, it is changed to be false.
boolean	isFalse() Tests to see if the value is currently false.
boolean	isTrue() Tests to see if the value is currently true.
boolean	isUseTimedOutExceptionSet() Used to determine whether or not TimedOutException will be thrown by methods when timout periods expire.
void	setUseTimedOutException(boolean useException) Used to change the timeout behavior of methods on the implementing classes.
void	setValue(boolean newValue) Sets the value to the specified new value.
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.
void	toggleValue() Toggles the value from true to false of from false to true.
String	toString() Shows the classname and current value.
void	waitForValueToChange() Waits for the value to change from its current value.
boolean	waitForValueToChange(long msTimeout) Waits for the value to change from its current value.
void	waitToSetFalse() Waits for the value to become true and then sets it to be false.
boolean	waitToSetFalse(long msTimeout) Waits for the value to become true and then sets it to be false.
void	waitToSetTrue() Waits for the value to become false and then sets it to be true.
boolean	waitToSetTrue(long msTimeout) Waits for the value to become false and then sets it to be true.
void	waitUntilFalse() Waits for the value to become false.
boolean	waitUntilFalse(long msTimeout) Waits for the value to become false.
void	waitUntilTrue() Waits for the value to become true.
boolean	waitUntilTrue(long msTimeout) Waits for the value to become true.
void	waitUntilValueIs(boolean targetValue) Waits for the value to match the specified target value.
boolean	waitUntilValueIs(boolean targetValue, long msTimeout) Waits for the value to match the specified target value.

Methods inherited from class java.lang.Object

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

Constructor Detail

SyncBoolean

public SyncBoolean(boolean initialValue,
                   Object lock,
                   boolean useTimedOutException)

Builds an instance with the specified initial value. The lock object is synchronized on internally to control concurrent access (see getLockObject()). The useTimedOutException flag indicates whether or not a TimedOutException will be thrown when methods timeout (see explanation).

Parameters:

initialValue - the value to start with.

lock - the object to synchronize on. If null is passed, this is used.

useTimedOutException - if true, TimedOutException will be thrown from methods when they timeout. If false, timeouts are indicated by return value.

SyncBoolean

public SyncBoolean(boolean initialValue)

Builds an instance with the specified initial value. Synchronization will be on this and timeouts will not throw exceptions. Internally, the main constructor is called like this:

this(initialValue, null, false);

SyncBoolean

public SyncBoolean()

Builds an instance with an initial value of false. Synchronization will be on this and timeouts will not throw exceptions. Internally, the main constructor is called like this:

this(false, null, false);

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

setValue

public void setValue(boolean newValue)
              throws ShutdownException

Sets the value to the specified new value.

Parameters:

newValue - the value to change to.

Throws:

ShutdownException - see explanation.

isTrue

public boolean isTrue()

Tests to see if the value is currently true.

Returns:

true if the value is true, false if the value is false.

isFalse

public boolean isFalse()

Tests to see if the value is currently false.

Returns:

true if the value is false, false if the value is true.

toggleValue

public void toggleValue()
                 throws ShutdownException

Toggles the value from true to false of from false to true.

Throws:

ShutdownException - see explanation.

ifFalseSetTrue

public boolean ifFalseSetTrue()
                       throws ShutdownException

If the value is currently false, it is changed to be true. Either way, when this method call is complete, the value is true.

Returns:

true if the value was changed, false otherwise.

Throws:

ShutdownException - see explanation.

ifTrueSetFalse

public boolean ifTrueSetFalse()
                       throws ShutdownException

If the value is currently true, it is changed to be false. Either way, when this method call is complete, the value is false.

Returns:

true if the value was changed, false otherwise.

Throws:

ShutdownException - see explanation.

waitToSetTrue

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

Waits for the value to become false and then sets it to be true.

Parameters:

msTimeout - maximum number of milliseconds to wait. Use ThreadTools.NO_TIMEOUT (or 0) to indicate that the waiting should never timeout.

Returns:

true if successful, false if a timeout occurs (and the timeout option is not set to throw exceptions [see explanation]).

Throws:

InterruptedException - see explanation.

TimedOutException - see explanation.

ShutdownException - see explanation.

waitToSetTrue

public void waitToSetTrue()
                   throws InterruptedException,
                          ShutdownException

Waits for the value to become false and then sets it to be true. Equivalent to:

SyncBoolean sb = //... synchronized ( sb.getLockObject() ) { sb.waitUntilFalse(); sb.setValue(true); }

Throws:

InterruptedException - see explanation.

ShutdownException - see explanation.

waitToSetFalse

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

Waits for the value to become true and then sets it to be false.

Parameters:

msTimeout - maximum number of milliseconds to wait. Use ThreadTools.NO_TIMEOUT (or 0) to indicate that the waiting should never timeout.

Returns:

true if successful, false if a timeout occurs (and the timeout option is not set to throw exceptions [see explanation]).

Throws:

InterruptedException - see explanation.

TimedOutException - see explanation.

ShutdownException - see explanation.

waitToSetFalse

public void waitToSetFalse()
                    throws InterruptedException,
                           ShutdownException

Waits for the value to become true and then sets it to be false.

Throws:

InterruptedException - see explanation.

ShutdownException - see explanation.

waitUntilTrue

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

Waits for the value to become true.

Parameters:

msTimeout - maximum number of milliseconds to wait. Use ThreadTools.NO_TIMEOUT (or 0) to indicate that the waiting should never timeout.

Returns:

true if successful, false if a timeout occurs (and the timeout option is not set to throw exceptions [see explanation]).

Throws:

InterruptedException - see explanation.

TimedOutException - see explanation.

ShutdownException - see explanation.

waitUntilTrue

public void waitUntilTrue()
                   throws InterruptedException,
                          ShutdownException

Waits for the value to become true.

Throws:

InterruptedException - see explanation.

ShutdownException - see explanation.

waitUntilFalse

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

Waits for the value to become false.

Parameters:

msTimeout - maximum number of milliseconds to wait. Use ThreadTools.NO_TIMEOUT (or 0) to indicate that the waiting should never timeout.

Returns:

true if successful, false if a timeout occurs (and the timeout option is not set to throw exceptions [see explanation]).

Throws:

InterruptedException - see explanation.

TimedOutException - see explanation.

ShutdownException - see explanation.

waitUntilFalse

public void waitUntilFalse()
                    throws InterruptedException,
                           ShutdownException

Waits for the value to become false.

Throws:

InterruptedException - see explanation.

ShutdownException - see explanation.

waitForValueToChange

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

Waits for the value to change from its current value.

Parameters:

msTimeout - maximum number of milliseconds to wait. Use ThreadTools.NO_TIMEOUT (or 0) to indicate that the waiting should never timeout.

Returns:

true if successful, false if a timeout occurs (and the timeout option is not set to throw exceptions [see explanation]).

Throws:

InterruptedException - see explanation.

TimedOutException - see explanation.

ShutdownException - see explanation.

waitForValueToChange

public void waitForValueToChange()
                          throws InterruptedException,
                                 ShutdownException

Waits for the value to change from its current value.

Throws:

InterruptedException - see explanation.

ShutdownException - see explanation.

waitUntilValueIs

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

Waits for the value to match the specified target value.

Parameters:

targetValue - the value to wait for.

msTimeout - maximum number of milliseconds to wait. Use ThreadTools.NO_TIMEOUT (or 0) to indicate that the waiting should never timeout.

Returns:

true if successful, false if a timeout occurs (and the timeout option is not set to throw exceptions [see explanation]).

Throws:

InterruptedException - see explanation.

TimedOutException - see explanation.

ShutdownException - see explanation.

waitUntilValueIs

public void waitUntilValueIs(boolean targetValue)
                      throws InterruptedException,
                             ShutdownException

Waits for the value to match the specified target value.

Parameters:

targetValue - the value to wait for.

Throws:

InterruptedException - see explanation.

ShutdownException - see explanation.

toString

public String toString()

Shows the classname and current value.

Overrides:

toString in class Object