org.xmlBlaster.util
Class Timeout

java.lang.Object
  java.lang.Thread
      org.xmlBlaster.util.Timeout

All Implemented Interfaces:

java.lang.Runnable

public class Timeout

extends java.lang.Thread

Allows you be called back after a given delay.

Note that this class should be called Timer, but with JDK 1.3 there will be a java.util.Timer.

There is a single background thread that is used to execute the I_Timeout.timeout() callback. Timer callbacks should complete quickly. If a timeout() takes excessive time to complete, it "hogs" the timer's task execution thread. This can, in turn, delay the execution of subsequent tasks, which may "bunch up" and execute in rapid succession when (and if) the offending task finally completes.

This singleton is thread-safe.

This class does not offer real-time guarantees, but usually notifies you within ~ 20 milliseconds of the scheduled time.

Adding or removing a timer is good performing, also when huge amounts of timers (> 1000) are used.
Feeding of 10000: 10362 adds/sec and all updates came in 942 millis (600MHz Linux PC with Sun JDK 1.3.1) *

TODO: Use a thread pool to dispatch the timeout callbacks.

Example:

  public class MyClass implements I_Timeout {
    ...
    Timeout timeout = new Timeout("TestTimer");
    Timestamp timeoutHandle = timeout.addTimeoutListener(this, 4000L, "myTimeout");
    ...
    public void timeout(Object userData) {
       // userData contains String "myTimeout"
       System.out.println("Timeout happened");
       ...
       // If you want to activate the timer again:
       timeoutHandle = timeout.addTimeoutListener(this, 4000L, "myTimeout");
    }
    ...
    // if you want to refresh the timer:
    timeoutHandle = timeout.refreshTimeoutListener(timeoutHandle, 1500L);
    ...
  }
 

Or a short form:

 Timeout timeout = new Timeout("TestTimer");
 
 Timestamp timeoutHandle = timeout.addTimeoutListener(new I_Timeout() {
    public void timeout(Object userData) {
       System.out.println("Timeout happened");
       System.exit(0);
    }
 }, 2000L, null);
 

JDK 1.2 or higher only.

Author:

xmlBlaster@marcelruff.info

See Also:

TimeoutTest

Field Summary

private boolean	debug Switch on debugging output
private java.util.TreeMap	map Sorted map
private boolean	mapHasNewEntry To avoid sync
private static java.lang.String	ME Name for logging output
private boolean	ready On creation wait until thread started
private boolean	running Start/Stop the Timeout manager thread
private boolean	useWeakReference Hold only weak reference on callback object?

Fields inherited from class java.lang.Thread

MAX_PRIORITY, MIN_PRIORITY, NORM_PRIORITY

Constructor Summary

Timeout()
Create a timer thread with a strong reference on the callback objects.

Timeout(java.lang.String name)
Create a timer thread with a strong reference on the callback objects.

Timeout(java.lang.String name, boolean useWeakReference)

Method Summary

Timestamp	addOrRefreshTimeoutListener(I_Timeout listener, long delay, java.lang.Object userData, Timestamp key) Checks if key is null -> addTimeoutListener else refreshTimeoutListener() in a thread save way.
Timestamp	addTimeoutListener(I_Timeout listener, long delay, java.lang.Object userData) Add a listener which gets informed after 'delay' milliseconds.
long	elapsed(Timestamp key) How long am i running.
int	getSize() Get number of current used timers.
long	getTimeout(Timestamp key) Access the end of life span.
boolean	isExpired(Timestamp key) Is this handle expired?
static void	main(java.lang.String[] args) Method for testing only.
Timestamp	refreshTimeoutListener(Timestamp key, long delay) Refresh a listener before the timeout happened.
void	removeAll() Reset all pending timeouts.
void	removeTimeoutListener(Timestamp key) Remove a listener before the timeout happened.
void	run() Starts the Timeout manager thread.
void	shutdown() Reset and stop the Timeout manager thread.
long	spanToTimeout(Timestamp key) How long to my timeout.
(package private) static void	testStrongReference() Eample for the standard case
(package private) static void	testWeakReference() Test a weak reference

Methods inherited from class java.lang.Thread

activeCount, checkAccess, countStackFrames, currentThread, destroy, dumpStack, enumerate, getContextClassLoader, getName, getPriority, getThreadGroup, holdsLock, interrupt, interrupted, isAlive, isDaemon, isInterrupted, join, join, join, resume, setContextClassLoader, setDaemon, setName, setPriority, sleep, sleep, start, stop, stop, suspend, toString, yield

Methods inherited from class java.lang.Object

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

Field Detail

ME

private static java.lang.String ME

Name for logging output

map

private java.util.TreeMap map

Sorted map

running

private boolean running

Start/Stop the Timeout manager thread

ready

private boolean ready

On creation wait until thread started

debug

private final boolean debug

Switch on debugging output

See Also:

Constant Field Values

useWeakReference

private final boolean useWeakReference

Hold only weak reference on callback object?

mapHasNewEntry

private boolean mapHasNewEntry

To avoid sync

Constructor Detail

Timeout

public Timeout()

Create a timer thread with a strong reference on the callback objects.

Timeout

public Timeout(java.lang.String name)

Create a timer thread with a strong reference on the callback objects.

Parameters:

name - The name of the thread

Timeout

public Timeout(java.lang.String name,
               boolean useWeakReference)

Parameters:

name - The name of the thread

useWeakReference - If true the reference on your I_Timeout implementation is only weak referenced and may be garbage collected even that we hold a weak reference.

Method Detail

getSize

public int getSize()

Get number of current used timers.

Returns:

The number of active timers

run

public void run()

Starts the Timeout manager thread.

addTimeoutListener

public final Timestamp addTimeoutListener(I_Timeout listener,
                                          long delay,
                                          java.lang.Object userData)

Add a listener which gets informed after 'delay' milliseconds.

After the timeout happened, you are not registered any more. If you want to cycle timeouts, you need to register again.

Parameters:

listener - Your callback handle (you need to implement this interface).

delay - The timeout in milliseconds. You can pass 0L and the Timeout thread will fire immediately, this can be useful to dispatch a task to the timeoutlistener

userData - Some arbitrary data you supply, it will be routed back to you when the timeout occurs through method I_Timeout.timeout().

Returns:

A handle which you can use to unregister with removeTimeoutListener().

refreshTimeoutListener

public final Timestamp refreshTimeoutListener(Timestamp key,
                                              long delay)
                                       throws XmlBlasterException

Refresh a listener before the timeout happened.

NOTE: The returned timeout handle is different from the original one.

NOTE: If you are not sure if the key has elapsed already try this:

 timeout.removeTimeoutListener(timeoutHandle);
 timeoutHandle = timeout.addTimeoutListener(this, "1000L", "UserData");
 

Parameters:

key - The timeout handle you received by a previous addTimeoutListener() call.
It is invalid after this call.

delay - The timeout in milliseconds measured from now.

Returns:

A new handle which you can use to unregister with removeTimeoutListener()

Throws:

XmlBlasterException - if key is null or unknown or invalid because timer elapsed already

addOrRefreshTimeoutListener

public final Timestamp addOrRefreshTimeoutListener(I_Timeout listener,
                                                   long delay,
                                                   java.lang.Object userData,
                                                   Timestamp key)
                                            throws XmlBlasterException

Checks if key is null -> addTimeoutListener else refreshTimeoutListener() in a thread save way.
Note however that your passed key is different from the returned key and you need to synchronize this call to avoid having a stale key (two threads enter this method the same time, the key gets invalid by the first thread and the second passed a stale key as the first thread has not yet returned to update 'key')

Throws:

XmlBlasterException

removeTimeoutListener

public final void removeTimeoutListener(Timestamp key)

Remove a listener before the timeout happened.

Parameters:

key - The timeout handle you received by a previous addTimeoutListener() call.

isExpired

public final boolean isExpired(Timestamp key)

Is this handle expired?

Parameters:

key - The timeout handle you received by a previous addTimeoutListener() call

Returns:

true/false

spanToTimeout

public final long spanToTimeout(Timestamp key)

How long to my timeout.

Parameters:

key - The timeout handle you received by a previous addTimeoutListener() call.

Returns:

Milliseconds to timeout, or -1 if not known.

elapsed

public final long elapsed(Timestamp key)

How long am i running.

Parameters:

key - The timeout handle you received by a previous addTimeoutListener() call.

Returns:

Milliseconds since creation, or -1 if not known.

getTimeout

public final long getTimeout(Timestamp key)

Access the end of life span.

Parameters:

key - The timeout handle you received by a previous addTimeoutListener() call.

Returns:

Time in milliseconds since midnight, January 1, 1970 UTC or -1 if not known.

removeAll

public final void removeAll()

Reset all pending timeouts.

shutdown

public void shutdown()

Reset and stop the Timeout manager thread.

main

public static void main(java.lang.String[] args)
                 throws java.lang.Exception

Method for testing only.

Invoke: java -Djava.compiler= org.xmlBlaster.util.Timeout

Throws:

java.lang.Exception

testStrongReference

static void testStrongReference()

Eample for the standard case

testWeakReference

static void testWeakReference()

Test a weak reference