GNUWorld Timer System

The gnuworld timer system allows for services clients to be notified of timed events. Timed events can be registered for any time in the future, and may optionally supply an argument to be returned to the timed event handler.

Each timed event is assigned a unique identification number. This timerID is returned to the object requesting a timed event upon registration, and is also passed to the timed event handler. Each services client may register for any number of timed events, and the expiration times of each event may overlap.

Timer Registration

For an xClient subclass to receive timed events, each event must be scheduled (registered) in advance. This is done by calling the xServer::RegisterTimer method:

virtual timerID RegisterTimer( const time_t& absoluteTime, xClient* theClient, void* data = 0 ) ;

This method has the following arguments:

const time_t& absoluteTime: This is the (absolute) time at which the requested timed event is to be executed. The units for this are seconds (at present), but may change in favor of increased resolution in the future.
 
Xclient* theClient: The services client requesting the timed event. This client will be notified when the timed event has expired (see below). This variable must be non-NULL, and is typically "this."
 
void* data = 0: This is the optional argument to be passed back to the timer event handler. This variable may be NULL, or may be omitted all together (hence the default parameter of 0), in which case NULL will be passed to the timer handler. It is important to consider what to pass to a timer handler (see below)

Returns: The unique identifier of a newly created timed event. Note that timerID's may be reused, but there will never be two timers with the same timerID simultaneously. The timerID type is a public typedef in xServer.

Choosing a Timed Event Argument

It is possible to supply an argument to be returned to your timer handler. There are several important considerations in choosing an argument for this purpose:

Of course, once the timer handler method is invoked, and processing of the timed event completes, do not forget to deallocate the method argument, if applicable. Failing to deallocate memory allocated on the heap is a memory leak.

Timer Handler

When a timed event expires, a timer handler method is invoked by the timer system. Passed to this handler are the unique timer identification and the optional argument passed to the timer registration method.

The base class xClient has a timer handler method:

virtual int OnTimer( xServer::timerID, void* ) ;

Arguments:

xServer::timerID: The unique identifier of this timer. This is used for tracking purposes inside the system during the life of this timed event. Note that the timerID may be reused once a timed event expires.
 
void*: This is the optional argument that was passed to the timer registration method. This variable may be NULL, depending on the value given when the timer was registered.

Returns: Currently, the return type of this method is not used, but this may change in the future.

NOTE: The OnTimer() method must NOT block. This could disrupt the entire system.

UnregisterTimer

Timed events may be unregistered at any time. The following xServer method provides this functionality:

virtual bool UnregisterTimer( const timerID&, void*& ) ;

Arguments:

const timerID&: The unique identifier of the timer to be removed.
 
void*&: A reference to the location at which to store the data object passed as argument to RegisterTimer(). If this argument is NULL, the timer argument is ignored. Otherwise, this variable is pointer to the address at which the timer handler is located. Be sure to retrieve any argument passed to the timer registration method that is allocated on the heap to prevent memory leaks.

Returns: True if the timerID was successfully located and removed, false otherwise.