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

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

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

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

Collaboration graph
[legend]
List of all members.

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 
)

Checks if key is 0 -> addTimeoutListener else refreshTimeoutListener() in a thread save way.

Parameters:
key If <= 0 we add a new timer, else lookup given key and refresh
Exceptions:
XmlBlasterException if timer is not started

Definition at line 150 of file Timeout.cpp.

References addTimeoutListener(), org::xmlBlaster::util::I_Log::call(), and refreshTimeoutListener().

Referenced by org::xmlBlaster::util::dispatch::ConnectionsHandler::startPinger().

void org::xmlBlaster::util::Timeout::removeTimeoutListener ( org::xmlBlaster::util::Timestamp  key  ) 

Remove a listener before the timeout happened.

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

Definition at line 159 of file Timeout.cpp.

References org::xmlBlaster::util::I_Log::call().

Referenced by org::xmlBlaster::util::dispatch::ConnectionsHandler::~ConnectionsHandler().

bool org::xmlBlaster::util::Timeout::isExpired ( org::xmlBlaster::util::Timestamp  key  ) 

Is this handle expired?

Parameters:
key The timeout handle you received by a previous addTimeoutListener() call
Returns:
true/false

Definition at line 166 of file Timeout.cpp.

References org::xmlBlaster::util::I_Log::call().

long org::xmlBlaster::util::Timeout::spanToTimeout ( org::xmlBlaster::util::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.

Definition at line 173 of file Timeout.cpp.

References org::xmlBlaster::util::I_Log::call(), getTimeout(), org::xmlBlaster::util::TimestampFactory::getTimestamp(), and org::xmlBlaster::util::Constants::MILLION.

long org::xmlBlaster::util::Timeout::getTimeout ( org::xmlBlaster::util::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.

Definition at line 183 of file Timeout.cpp.

References org::xmlBlaster::util::I_Log::call(), and org::xmlBlaster::util::Constants::MILLION.

Referenced by spanToTimeout().

void org::xmlBlaster::util::Timeout::removeAll (  ) 

Reset all pending timeouts.

Definition at line 190 of file Timeout.cpp.

References org::xmlBlaster::util::I_Log::call().

Referenced by shutdown().

void org::xmlBlaster::util::Timeout::shutdown (  ) 

Reset and stop the Timeout manager thread.

Definition at line 197 of file Timeout.cpp.

References org::xmlBlaster::util::I_Log::call(), org::xmlBlaster::util::thread::Condition::notify(), and removeAll().

Referenced by org::xmlBlaster::test::TestTimeout::tearDown(), and ~Timeout().

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

This is the method which has to be implemented by the user.

Implements org::xmlBlaster::util::thread::Thread.

Definition at line 214 of file Timeout.cpp.

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


The documentation for this class was generated from the following files: