TSLTimer Class Reference

Detailed Description

This defines the interface for timer objects which provide time events for the Time Server.

The timer notifies the Time Server of a time event by calling TSLTimeServer::tick, passing the new time.

When starting the timer, users can specify a time origin that is different to the current time. This allows the timer to provide past or future times at every tick.

The default timer runs in its own separate thread. Where necessary, users will need to ensure thread-safety of the tick() method of any TSLTimeClient-derived classes.

Public Member Functions
virtual TSLTime64	calibrate (TSLTimeInterval const &duration, TSLTimerCalibrationProgress *callback=0)=0
virtual void	duration (TSLTimeInterval const &interval)=0
virtual TSLTimeInterval const &	duration () const =0
virtual bool	pause ()=0
virtual void	resetDuration ()=0
virtual void	setCalibration (TSLTime64 calibration)=0
virtual TSLTimerListener *	setListener (TSLTimerListener *listener)=0
virtual bool	start ()=0
virtual TSLTimeInstant const &	startTime () const =0
virtual void	startTime (TSLTimeInstant const &timeOrigin)=0
virtual TSLTimerStateEnum	state () const =0
virtual bool	stop ()=0
virtual TSLTimeUInt32	tickCount () const =0
virtual TSLTimeInterval const &	tickInterval () const =0
virtual bool	tickInterval (TSLTimeInterval const &interval)=0
virtual TSLTimeInstant const &	time () const =0
virtual double	timeCompression () const =0
virtual bool	timeCompression (double compression)=0
virtual TSLTimeHelper const &	timeHelper () const =0
	TSLTimer (TSLTimeServer *server=0)
virtual	~TSLTimer ()

Protected Attributes
TSLTimeServer *	m_timeServer
TSLTimerListener *	m_listener

Constructor & Destructor Documentation

TSLTimer()

TSLTimer::TSLTimer ( TSLTimeServer * server = 0 )

inline

Constructor. Attaches the timer to the timer server.

Also initialises the listener to NULL.

Parameters

server

A pointer to the time server. Default value = 0.

~TSLTimer()

TSLTimer::~TSLTimer ( )

inlinevirtual

Virtual destructor.

Member Function Documentation

calibrate()

virtual TSLTime64 TSLTimer::calibrate ( TSLTimeInterval const & duration, TSLTimerCalibrationProgress * callback = 0 )

pure virtual

This method is a request to the timer to calibrate itself.

Parameters

duration	The length of time that the calibration should last for.
callback	A callback function that is called by the calibration method to indicate progress.

Returns

a value that should be passed to the timer's setCalibration() method before the timer is started. Normally users will store this value in an .ini file or the Window's registry.

duration() [1/2]

virtual TSLTimeInterval const & TSLTimer::duration ( ) const

pure virtual

A null duration signifies that the timer will beat indefinitely.

Returns

The value of the timer duration.

duration() [2/2]

virtual void TSLTimer::duration ( TSLTimeInterval const & interval )

pure virtual

The duration over which the timer will provide ticks. Once this interval has elapsed, the timer will automatically stop.

Parameters

interval

The duration as a TSLTimeInterval object.

If interval is TSLTimeInterval::nullInterval(), then the duration is reset i.e. the timer will keep providing ticks until explicitly stopped.

pause()

virtual bool TSLTimer::pause ( )

pure virtual

This method pauses the timer.

If the timer is paused successfully, returns true, false otherwise.

resetDuration()

virtual void TSLTimer::resetDuration ( )

pure virtual

Resets the duration i.e. the timer will keep providing ticks until explicitly stopped.

setCalibration()

virtual void TSLTimer::setCalibration ( TSLTime64 calibration )

pure virtual

Sets the time's calibration value.

Parameters

calibration

The value returned from the calibrate() method.

setListener()

virtual TSLTimerListener * TSLTimer::setListener ( TSLTimerListener * listener )

pure virtual

Attaches a TSLTimerListener-derived object. The Timer will notify this object at the start of a tick event and at the end of the tick event. It will also send a notification when it is started, stopped and paused.

Parameters

listener

A pointer to a TSLTimerListener interface. This can be NULL.

Returns

the previous listener.

Note

the Timer does not assume ownership of the listener. It is the user's responsibility to manage the lifetime of listeners.

start()

virtual bool TSLTimer::start ( )

pure virtual

This method starts the timer.

If the timer is started successfully, returns true, false otherwise.

startTime() [1/2]

virtual TSLTimeInstant const & TSLTimer::startTime ( ) const

pure virtual

Returns the value of the time origin.

startTime() [2/2]

virtual void TSLTimer::startTime ( TSLTimeInstant const & timeOrigin )

pure virtual

This method sets the starting time to the supplied value. The time at each subsequent tick will be based on this origin.

If timeOrigin is not supplied, then the starting time is set to the current time.

Parameters

timeOrigin

The time origin with respect to which time events occur.

state()

virtual TSLTimerStateEnum TSLTimer::state ( ) const

pure virtual

Returns the current state that the Timer is in.

stop()

virtual bool TSLTimer::stop ( )

pure virtual

This method stops the timer.

If the timer is stopped successfully, returns true, false otherwise.

tickCount()

virtual TSLTimeUInt32 TSLTimer::tickCount ( ) const

pure virtual

Returns the current tick count.

tickInterval() [1/2]

virtual TSLTimeInterval const & TSLTimer::tickInterval ( ) const

pure virtual

Returns the current tick interval as a TSLTimeInterval object.

tickInterval() [2/2]

virtual bool TSLTimer::tickInterval ( TSLTimeInterval const & interval )

pure virtual

Changes the tick interval of the timer based on the supplied TSLTimeInterval object.

This can be called at any time.

Parameters

tickInterval

The required tick interval as a TSLTimeInterval object.

Returns

true if the tick interval was successfully changed, false otherwise.

If the tick interval is negative, the timer will run backwards in time.

time()

virtual TSLTimeInstant const & TSLTimer::time ( ) const

pure virtual

Returns the current time.

timeCompression() [1/2]

virtual double TSLTimer::timeCompression ( ) const

pure virtual

Returns the value of the time compression factor.

timeCompression() [2/2]

virtual bool TSLTimer::timeCompression ( double compression )

pure virtual

Set the time compression factor.

Parameters

compression

The time compression factor.

Returns

true if the value has been set successfully, false otherwise. If the value of compression is such that the maths will overflow, then false is returned.

Negative values are treated as positive values.

A value of 0 will be treated as 1.0.

If compression is > 1.0, then time is speeded up i.e. the elapsed time between ticks is scaled up by this number. If compression is < 1.0, then time is slowed down i.e. the elapsed time between ticks is scaled down by this number.

The compression factor is also applied to the duration.

timeHelper()

virtual TSLTimeHelper const & TSLTimer::timeHelper ( ) const

pure virtual

Returns a (const) reference to a time helper. Derived classes must provide an implementation for this.

Member Data Documentation

m_listener

TSLTimerListener* TSLTimer::m_listener

protected

m_timeServer

TSLTimeServer* TSLTimer::m_timeServer

protected