A class representing a system timer. More...

#include <timer.h>

Inheritance diagram for PTimer:

Collaboration diagram for PTimer:

Classes
class	List

Public Member Functions
Construction
	PTimer (long milliseconds=0, int seconds=0, int minutes=0, int hours=0, int days=0)
	Create a new timer object and start it in one shot mode for the specified amount of time. More...

	PTimer (const PTimeInterval &time)

	PTimer (const PTimer &timer)

PTimer &	operator= (const PTimer &timer)
	Restart the timer in one shot mode using the specified time value. More...

	PTIMER_OPERATORS (PTimer)

virtual	~PTimer ()
	Destroy the timer object, stops timer if it is running. More...

Overrides from class PObject
virtual void	PrintOn (ostream &strm) const
	Output the time interval to the I/O stream. More...

Control functions
virtual void	SetMilliSeconds (PInt64 msecs)
	Set the number of milliseconds for the time interval. More...

void	RunContinuous (const PTimeInterval &time)
	Start a timer in continous cycle mode. More...

void	Stop (bool wait=true)
	Stop a running timer. More...

PBoolean	IsRunning () const
	Determine if the timer is currently running. More...

void	Reset ()
	Restart a timer continuing from the time it was initially. More...

PTimeInterval	GetResetTime () const
	Get the time this timer was set to initially. More...

Notification functions
virtual void	OnTimeout ()
	This function is called on time out. More...

const PNotifier &	GetNotifier () const
	Get the current call back function that is called whenever the timer expires. More...

void	SetNotifier (const PNotifier &func)
	Set the call back function that is called whenever the timer expires. More...

Member access
PInt64	GetMilliSeconds () const
	Return number of milliseconds left in timer. More...

Public Member Functions inherited from PTimeInterval
	PTimeInterval (PInt64 millisecs=0)
	Create a new time interval object. More...

	PTimeInterval (PInt64 millisecs, long seconds, long minutes=0, long hours=0, int days=0)

	PTimeInterval (const PString &str)

PObject *	Clone () const
	Create a new copy of the time interval. More...

virtual Comparison	Compare (const PObject &obj) const
	Rank the two time intervals. More...

virtual void	PrintOn (ostream &strm) const
	Output the time interval to the I/O stream. More...

virtual void	ReadFrom (istream &strm)
	Input the time interval from the I/O stream. More...

long	GetSeconds () const
	Get the number of whole seconds for the time interval. More...

long	GetMinutes () const
	Get the number of whole minutes for the time interval. More...

int	GetHours () const
	Get the number of whole hours for the time interval. More...

int	GetDays () const
	Get the number of whole days for the time interval. More...

DWORD	GetInterval () const
	Get the number of milliseconds for the time interval. More...

virtual void	SetInterval (PInt64 milliseconds=0, long seconds=0, long minutes=0, long hours=0, int days=0)
	Set the value of the time interval. More...

PTimeInterval	operator- () const
	Unary minus, get negative of time interval. More...

PTimeInterval	operator+ (const PTimeInterval &interval) const
	Add the two time intervals yielding a third time interval. More...

PTimeInterval &	operator+= (const PTimeInterval &interval)
	Add the second time interval to the first time interval. More...

PTimeInterval	operator- (const PTimeInterval &interval) const
	Subtract the two time intervals yielding a third time interval. More...

PTimeInterval &	operator-= (const PTimeInterval &interval)
	Subtract the second time interval from the first time interval. More...

PTimeInterval	operator* (int factor) const
	Multiply the time interval by a factor yielding a third time interval. More...

PTimeInterval &	operator*= (int factor)
	Multiply the time interval by a factor. More...

int	operator/ (const PTimeInterval &smaller) const
	Divide the time interval by another interval yielding a count. More...

PTimeInterval	operator/ (int factor) const
	Divide the time interval by a factor yielding a third time interval. More...

PTimeInterval &	operator/= (int factor)
	Divide the time interval by a factor. More...

bool	operator== (const PTimeInterval &interval) const
	Compare to the two time intervals. More...

bool	operator== (long msecs) const

bool	operator!= (const PTimeInterval &interval) const
	Compare to the two time intervals. More...

bool	operator!= (long msecs) const

bool	operator> (const PTimeInterval &interval) const
	Compare to the two time intervals. More...

bool	operator> (long msecs) const

bool	operator>= (const PTimeInterval &interval) const
	Compare to the two time intervals. More...

bool	operator>= (long msecs) const

bool	operator< (const PTimeInterval &interval) const
	Compare to the two time intervals. More...

bool	operator< (long msecs) const

bool	operator<= (const PTimeInterval &interval) const
	Compare to the two time intervals. More...

bool	operator<= (long msecs) const

PString	AsString (int decimals=3, Formats format=NormalFormat, int width=1) const

Public Member Functions inherited from PObject
unsigned	GetTraceContextIdentifier () const
	Get PTRACE context identifier. More...

void	SetTraceContextIdentifier (unsigned id)

void	GetTraceContextIdentifier (PObject &obj)

void	GetTraceContextIdentifier (PObject *obj)

void	SetTraceContextIdentifier (const PObject &obj)

void	SetTraceContextIdentifier (const PObject *obj)

virtual	~PObject ()

template<class CLS >
CLS *	CloneAs () const
	As for Clone() but converts to specified type. More...

virtual PINDEX	HashFunction () const
	This function yields a hash value required by the `PDictionary` class. More...

virtual const char *	GetClass (unsigned ancestor=0) const
	Get the current dynamic type of the object instance. More...

PBoolean	IsClass (const char *cls) const

virtual PBoolean	InternalIsDescendant (const char *clsName) const
	Determine if the dynamic type of the current instance is a descendent of the specified class. More...

__inline const PObject *	PTraceObjectInstance () const

virtual Comparison	CompareObjectMemoryDirect (const PObject &obj) const
	Determine the byte wise comparison of two objects. More...

bool	operator== (const PObject &obj) const
	Compare the two objects. More...

bool	operator!= (const PObject &obj) const
	Compare the two objects. More...

bool	operator< (const PObject &obj) const
	Compare the two objects. More...

bool	operator> (const PObject &obj) const
	Compare the two objects. More...

bool	operator<= (const PObject &obj) const
	Compare the two objects. More...

bool	operator>= (const PObject &obj) const
	Compare the two objects. More...

virtual void	ReadFrom (istream &strm)
	Input the contents of the object from the stream. More...

Static Public Member Functions
static List *	TimerList ()

Global real time functions
static PTimeInterval	Tick ()
	Get the number of milliseconds since some arbtrary point in time. More...

static unsigned	Resolution ()
	Get the smallest number of milliseconds that the timer can be set to. More...

Additional Inherited Members
Public Types inherited from PTimeInterval
enum	Formats { NormalFormat, IncludeDays, SecondsOnly }

Public Types inherited from PObject
enum	Comparison { LessThan = -1, EqualTo = 0, GreaterThan = 1 }
	Result of the comparison operation performed by the `Compare()` function. More...

Protected Member Functions inherited from PObject
	PObject ()
	Constructor for PObject, made protected so cannot ever create one on its own. More...

Protected Attributes inherited from PObject
unsigned	m_traceContextIdentifier

Friends inherited from PObject

Detailed Description

A class representing a system timer.

The time interval ancestor value is the amount of time left in the timer.

A timer on completion calls the virtual function OnTimeout(). This will in turn call the callback function provided by the instance. The user may either override the virtual function or set a callback as desired.

A list of active timers is maintained by the applications PProcess instance and the timeout functions are executed in the context of a separate thread of execution.

Also timers are not very accurate in sub-second delays, even though you can set the timer in milliseconds, its accuracy is only to -0/+250 ms. Even more (potentially MUCH more) if there are large delays in the user call-back functions and many of them exhausting the thread pool.

When you subclass PTimer you MUST call Stop() in destructor. This guarantees that object not destroyed in OnTimeout execution.

Finally, while the timers "system" threads are fully thread safe, the PTimeInterval on which it is based is not. So care is required for user threads on platforms where a 64 bit integer access is not an atomic operation.

Constructor & Destructor Documentation

PTimer::PTimer	(	long	milliseconds = `0`,
		int	seconds = `0`,
		int	minutes = `0`,
		int	hours = `0`,
		int	days = `0`
	)

Create a new timer object and start it in one shot mode for the specified amount of time.

If the time was zero milliseconds then the timer is {not} started, ie the callback function is not executed immediately.

Parameters

milliseconds	Number of milliseconds for timer.
seconds	Number of seconds for timer.
minutes	Number of minutes for timer.
hours	Number of hours for timer.
days	Number of days for timer.

PTimer::PTimer ( const PTimeInterval & time )

Parameters

time	New time interval for timer.

PTimer::PTimer ( const PTimer & timer )

Parameters

timer Timer to copy.

virtual PTimer::~PTimer ( )

virtual

Destroy the timer object, stops timer if it is running.

Member Function Documentation

PInt64 PTimer::GetMilliSeconds ( ) const

virtual

Return number of milliseconds left in timer.

Reimplemented from PTimeInterval.

const PNotifier& PTimer::GetNotifier ( ) const

Get the current call back function that is called whenever the timer expires.

This is called by the OnTimeout() function.

Returns: current notifier for the timer.

PTimeInterval PTimer::GetResetTime ( ) const

Get the time this timer was set to initially.

PBoolean PTimer::IsRunning ( ) const

Determine if the timer is currently running.

This really is only useful for one shot timers as repeating timers are always running.

Returns: true if timer is still counting.

virtual void PTimer::OnTimeout ( )

virtual

This function is called on time out.

That is when the system timer processing decrements the timer from a positive value to less than or equal to zero. The interval is then reset to zero and the function called.

Please note that the application should not execute large amounts of code in this call back or the accuracy of ALL timers can be severely impacted.

The default behaviour of this function is to call the PNotifier callback function.

Reimplemented in PPoolTimer< Work_T, Pool_T >, and PPoolTimer< Base_T, Pool_T >.

PTimer& PTimer::operator= ( const PTimer & timer )

Restart the timer in one shot mode using the specified time value.

If the timer was already running, the "time left" is simply reset.

Returns: reference to the timer.

Parameters

timer New time interval for timer.

virtual void PTimer::PrintOn ( ostream & strm ) const

virtual

Output the time interval to the I/O stream.

This outputs the number of milliseconds as a signed decimal integer number.

Parameters

strm	I/O stream to output the time interval.

Reimplemented from PObject.

PTimer::PTIMER_OPERATORS ( PTimer )

void PTimer::Reset ( )

Restart a timer continuing from the time it was initially.

static unsigned PTimer::Resolution ( )

static

Get the smallest number of milliseconds that the timer can be set to.

All actual timing events will be rounded up to the next value. This is typically the platforms internal timing units used in the Tick() function.

Returns: minimum number of milliseconds per timer "tick".

void PTimer::RunContinuous ( const PTimeInterval & time )

Start a timer in continous cycle mode.

Whenever the timer runs out it is automatically reset to the time specified. Thus, it calls the notification function every time interval.

virtual void PTimer::SetMilliSeconds ( PInt64 msecs )

virtual

Set the number of milliseconds for the time interval.

Note, this will restart the timer in the current mode.

Reimplemented from PTimeInterval.

void PTimer::SetNotifier ( const PNotifier & func )

Set the call back function that is called whenever the timer expires.

This is called by the OnTimeout() function.

void PTimer::Stop ( bool wait = true )

Stop a running timer.

The timer will not call the notification function and is reset back to the original timer value. Thus when the timer is restarted it begins again from the beginning.

While OnTimeout() is running this method will wait until OnTimeout() will finish.

The wait flag is deprecated and not used in this implementation.

static PTimeInterval PTimer::Tick ( )

static

Get the number of milliseconds since some arbtrary point in time.

This is a platform dependent function that yields a real time counter.

Note that even though this function returns milliseconds, the value may jump in minimum quanta according the platforms timer system, eg under MS-DOS and MS-Windows the values jump by 55 every 55 milliseconds. The Resolution() function may be used to determine what the minimum time interval is.

Returns: millisecond counter.

static List* PTimer::TimerList ( )

static

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

timer.h

Classes

Public Member Functions

Static Public Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation