org.openuat.util
Class SafetyBeltTimer

java.lang.Object
  org.openuat.util.SafetyBeltTimer

All Implemented Interfaces:

java.lang.Runnable

public class SafetyBeltTimer
extends java.lang.Object
implements java.lang.Runnable

This class implements a "grenade timer" that will let any loop bail out with a timeout when it is stuck for too long waiting for something. To use it, simply construct a SafetyBeltTimer object with the number of milliseconds the next operation should take at maximum. The timer is automatically started on construction and runs in a separate thread. If there are multiple steps or rounds in some operation that are expected to take this time each, then reset() can be used to set the timer back to zero while still leaving it running. isTriggered() can be used to query if the timer has already expired and e.g. an outer loop should exit gracefully.
There is no need to explicitly stop the thread, it will just time out and stop. Sample code for this simple use case:

 {
                SafetyBeltTimer timer = new SafetyBeltTimer(timeoutMs, null);
                while (something && ! timer.isTriggered()) {
                        // ... whatever might take long
                        if (made some progress) timer.reset();
                        // ... maybe some more blocking code
                }
 }
 

Additionally, an InputStream can be passed to the timer on construction. When set to a valid object, its close() method will be called when the timer expires. This allows to exit even from a blocking read() that may be active while the timeout occurs. Sample code to use it that way:

 {
                SafetyBeltTimer timer = new SafetyBeltTimer(timeoutMs, channelFromRemote);
                try {
                        // ... whatever might take long, reading from channelFromRemote
                        // in this case explicitly stop the timer at the end so that it won't close channelFromRemote
                        timer.stop();
                }
                catch (IOException e) {
                        // there might have been a timeout
                }
                finally {
                        timer.stop();
                }
 }
 

Version:

1.0

Author:

Rene Mayrhofer

Constructor Summary

SafetyBeltTimer(int time, java.io.InputStream abortStream)

Method Summary

boolean	isTriggered() Returns true when the timer has triggered and the task should terminate.
void	reset() Allows to send a "heartbeat" signal to the timer by resetting it.
void	run() Implements the timer background thread.
void	stop() This stops the safety belt timer gracefully without triggering it.

Methods inherited from class java.lang.Object

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

Constructor Detail

SafetyBeltTimer

public SafetyBeltTimer(int time,
                       java.io.InputStream abortStream)

Parameters:

time - The time, in milliseconds, that this timer will use.

abortStream - If set, then this stream will be forcefully closed when the timer is triggered. This can be used for enforcing timeouts on blocking reads. Set to null to disable this functionality.

Method Detail

run

public void run()

Implements the timer background thread.

Specified by:

run in interface java.lang.Runnable

isTriggered

public boolean isTriggered()

Returns true when the timer has triggered and the task should terminate.

reset

public void reset()

Allows to send a "heartbeat" signal to the timer by resetting it. This allows to implement heartbeat like functionality where the timer can get reset whenever some progress is being made.

stop

public void stop()

This stops the safety belt timer gracefully without triggering it.