org::xmlBlaster::util::Timeout

org::xmlBlaster::util::Timeout Class Reference

Allows you be called back after a given delay. More...

Inheritance diagram for org::xmlBlaster::util::Timeout:

[legend]Collaboration diagram for org::xmlBlaster::util::Timeout:


Public Member Functions
	Timeout (org::xmlBlaster::util::Global &global)
	Create a timer thread.
	Timeout (org::xmlBlaster::util::Global &global, const std::string &name)
	Create a timer thread.
	~Timeout ()
void	join ()
	Used to join the thread used by this instance.
int	getSize () const
	Get number of current used timers.
org::xmlBlaster::util::Timestamp	addTimeoutListener (I_Timeout listener, long delay, void userData)
	Add a listener which gets informed after 'delay' milliseconds.
org::xmlBlaster::util::Timestamp	refreshTimeoutListener (org::xmlBlaster::util::Timestamp key, long delay)
	Refresh a listener before the timeout happened.
org::xmlBlaster::util::Timestamp	addOrRefreshTimeoutListener (I_Timeout listener, long delay, void userData, org::xmlBlaster::util::Timestamp key)
	Checks if key is 0 -> addTimeoutListener else refreshTimeoutListener() in a thread save way.
void	removeTimeoutListener (org::xmlBlaster::util::Timestamp key)
	Remove a listener before the timeout happened.
bool	isExpired (org::xmlBlaster::util::Timestamp key)
	Is this handle expired?
long	spanToTimeout (org::xmlBlaster::util::Timestamp key)
	How long to my timeout.
long	getTimeout (org::xmlBlaster::util::Timestamp key)
	Access the end of life span.
void	removeAll ()
	Reset all pending timeouts.
void	shutdown ()
	Reset and stop the Timeout manager thread.
void	run ()
	This is the method which has to be implemented by the user.

Detailed Description

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");
   org::xmlBlaster::util::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");
  org::xmlBlaster::util::Timestamp timeoutHandle = timeout.addTimeoutListener(new I_Timeout() {
        public void timeout(Object userData) {
           System.out.println("Timeout happened");
           System.exit(0);
        }
     },
     2000L, null);

Author:: xmlBlaster@marcelruff.info
laghi@swissinfo.org

Definition at line 82 of file Timeout.h.

Constructor & Destructor Documentation

org::xmlBlaster::util::Timeout::Timeout ( org::xmlBlaster::util::Global & global )

Create a timer thread.

Definition at line 20 of file Timeout.cpp.

References org::xmlBlaster::util::I_Log::call(), org::xmlBlaster::util::lexical_cast(), and org::xmlBlaster::util::I_Log::trace().

org::xmlBlaster::util::Timeout::Timeout	(	org::xmlBlaster::util::Global &	global,
		const std::string &	name
	)

Create a timer thread.

org::xmlBlaster::util::Timeout::~Timeout ( )

Definition at line 51 of file Timeout.cpp.

References org::xmlBlaster::util::I_Log::call(), join(), shutdown(), org::xmlBlaster::util::thread::Thread::sleep(), and org::xmlBlaster::util::I_Log::warn().

Member Function Documentation

void org::xmlBlaster::util::Timeout::join ( ) [virtual]

Used to join the thread used by this instance.

Don't call this method for detached running threads.

Reimplemented from org::xmlBlaster::util::thread::Thread.

Definition at line 86 of file Timeout.cpp.

References org::xmlBlaster::util::thread::Thread::join(), and org::xmlBlaster::util::I_Log::trace().

Referenced by ~Timeout().

int org::xmlBlaster::util::Timeout::getSize ( ) const

Get number of current used timers.

Returns:: The number of active timers

Definition at line 153 of file Timeout.h.

Timestamp org::xmlBlaster::util::Timeout::addTimeoutListener	(	I_Timeout *	listener,
		long	delay,
		void *	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.
	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().

Exceptions:

XmlBlasterException

if timer is not started

Definition at line 92 of file Timeout.cpp.

References org::xmlBlaster::util::I_Log::error(), org::xmlBlaster::util::TimestampFactory::getTimestamp(), org::xmlBlaster::util::Constants::MILLION, org::xmlBlaster::util::thread::Condition::notify(), org::xmlBlaster::util::I_Log::trace(), and org::xmlBlaster::util::USER_WRONG_API_USAGE.

Referenced by addOrRefreshTimeoutListener(), refreshTimeoutListener(), org::xmlBlaster::test::TestTimeout::testTimeout(), and org::xmlBlaster::test::TestTimeout::timeout().

Timestamp org::xmlBlaster::util::Timeout::refreshTimeoutListener	(	org::xmlBlaster::util::Timestamp	key,
		long	delay
	)

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(). -1: if key is null or unknown or invalid because timer elapsed already

Exceptions:

XmlBlasterException

if key<0 or timer is not started

Definition at line 124 of file Timeout.cpp.

References addTimeoutListener(), org::xmlBlaster::util::I_Log::call(), org::xmlBlaster::util::INTERNAL_ILLEGALARGUMENT, org::xmlBlaster::util::I_Log::trace(), and org::xmlBlaster::util::USER_WRONG_API_USAGE.

Referenced by addOrRefreshTimeoutListener().

Timestamp org::xmlBlaster::util::Timeout::addOrRefreshTimeoutListener	(	I_Timeout *	listener,
		long	delay,
		void *	userData,
		org::xmlBlaster::util::Timestamp	key
	)