Timers

Description

Scheduling timed and/or repeated operations.

A timer, represented by a CTimer object, allows to execute some user-defined function at a given time. The class can be used in one of two ways,

1. by setting a callback function of type FTimerCallback, or
2. by overriding the virtual method CTimer::OnTime().

The timed functions are effectively executed from inside TimerIterate() or TimerRun(), which is to be executed in some thread referred to as the timer thread. It is recommend, but not required, that the timer thread is the same as the main (UI) thread of the main application.

The timer can be executed by the main program in one of three ways:

1. If there is already an exisiting main event loop (e.g. via SDL), the non-blocking functions TimerIterate() and TimerGetDelay() should be used.
2. If the application does not have an own main loop, the functions TimerRun() (blocking), and TimerStop() may be used to easily implement one.
3. As a third option, a separate timer thread can be started with TimerStart() and later be stopped by TimerStop().

Note: For efficiency reasons (minimize wakeups and context switches), repeated (_interval > 0) timers should always defined such that the interval is a power of 2. They are aligned internally to times dividable by _interval in a way that they may happen earlier, but never later than specified.

Collaboration diagram for Timers:

Classes
class	CTimer
	Timer class. More...

Typedefs
typedef void	FTimerCallback(class CTimer *timer, void *data)
	Function type for timer callbacks. More...

Control functions (for the main program) ...
bool	TimerIterate ()
	Returns false if nothing was done.
TTicks	TimerGetDelay ()
	Returns number of milliseconds until next call to TimerIterate() is necessary, or -1 if no timer is pending.
void	TimerStart ()
	Start TimerRun() in a background thread, which is to be stopped using TimerStop(). All timer functions are then run from the same, namely that background thread.
int	TimerRun (bool catchSignals=true)
	Perform an endless loop calling timers until TimerStop() is called. More...
void	TimerStop ()
	Request TimerRun() to return at next occasion (can be called from any thread). If a dedicated timer thread was started, this is joined, too.

Typedef Documentation

FTimerCallback

typedef void FTimerCallback(class CTimer *timer, void *data)

Function type for timer callbacks.

Parameters

timer	The calling timer.
data	User data as passed to the CTimer object.

Definition at line 1574 of file base.H.

Function Documentation

TimerRun()

int TimerRun

(

bool

catchSignals = true

)

Perform an endless loop calling timers until TimerStop() is called.

Parameters

catchSignals

controls whether the signals SIGTERM ("exit nicely", default of the kill(1) command) and SIGINT (Ctrl-C) are caught temporarly and lead to an immediate return of this function.

Returns

the signal number if the function has been stopped by a caught signal, else 0.