PTimer Class Reference

A class representing a system timer. More...

`#include <timer.h>`

Inheritance diagram for PTimer:

## Public Types

typedef unsigned | IDType
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...

## Public Member Functions

IDType | GetTimerId () const
PAtomicInteger::IntegerType | GetNextSerialNumber ()
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= (DWORD milliseconds)
| Restart the timer in one shot mode using the specified time value. More...
PTimer & | operator= (const PTimeInterval &time)
PTimer & | operator= (const PTimer &timer)
virtual | ~PTimer ()
| Destroy the timer object, removing it from the applications timer list if it was running. More...
Control functions
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...
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 | Pause ()
| Pause a running timer. More...
void | Resume ()
| Restart a paused timer continuing at the time it was paused. More...
PBoolean | IsPaused () const
| Determine if the timer is currently paused. More...
void | Reset ()
| Restart a timer continuing from the time it was initially. More...
const 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...
PInt64 | GetAbsoluteTime () const
| Return absolute time timer will expire. More...
Public Member Functions inherited from PTimeInterval
| PTimeInterval (PInt64 millisecs=0)
| Create a new time interval object. More...
| PTimeInterval (long 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...
virtual void | SetMilliSeconds (PInt64 msecs)
| Set the number of milliseconds for the time interval. 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...
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
virtual | ~PObject ()
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...
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...

## Static Public Member Functions

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...
Static Public Member Functions inherited from PObject
static const char * | Class ()
| Get the name of the class as a C string. More...
static Comparison | InternalCompareObjectMemoryDirect (const PObject *obj1, const PObject *obj2, PINDEX size)
| Internal function caled from CompareObjectMemoryDirect() More...

## Additional Inherited Members

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

## 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 single thread of execution. There are many consequences of this: only one timeout function can be executed at a time and thus a user should not execute a lot of code in the timeout call-back functions or it will dealy the timely execution of other timers call-back functions.

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 delays in the user call-back functions.

Another trap is you cannot destroy a timer in its own call-back. There is code to cause an assert if you try but it is very easy to accidentally do this when you delete an object that contains an onject that contains the timer!

Finally static timers cause race conditions on start up and termination and should be avoided.

## Member Typedef Documentation

## IDType

typedef unsigned PTimer::IDType

## Constructor & Destructor Documentation

## PTimer() [1/3]

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() [2/3]

PTimer::PTimer | ( | const PTimeInterval & | time | ) |

Parameters

  time | New time interval for timer.

## PTimer() [3/3]

PTimer::PTimer | ( | const PTimer & | timer | ) |

Parameters

  timer | Timer to copy.

## ~PTimer()

virtual PTimer::~PTimer | ( |  | ) |

virtual

Destroy the timer object, removing it from the applications timer list if it was running.

## Member Function Documentation

## GetAbsoluteTime()

PInt64 PTimer::GetAbsoluteTime | ( |  | ) | const

inline

Return absolute time timer will expire.

## GetMilliSeconds()

PInt64 PTimer::GetMilliSeconds | ( |  | ) | const

virtual

Return number of milliseconds left in timer.

Reimplemented from PTimeInterval.

## GetNextSerialNumber()

PAtomicInteger::IntegerType PTimer::GetNextSerialNumber | ( |  | ) |

inline

## GetNotifier()

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.

## GetResetTime()

const PTimeInterval& PTimer::GetResetTime | ( |  | ) | const

Get the time this timer was set to initially.

## GetTimerId()

IDType PTimer::GetTimerId | ( |  | ) | const

inline

## IsPaused()

PBoolean PTimer::IsPaused | ( |  | ) | const

Determine if the timer is currently paused.

Returns
  true if timer paused.

## IsRunning()

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.

## OnTimeout()

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.

## operator=() [1/3]

PTimer& PTimer::operator= | ( | DWORD | milliseconds | ) |

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

  milliseconds | New time interval for timer.

## operator=() [2/3]

PTimer& PTimer::operator= | ( | const PTimeInterval & | time | ) |

Parameters

  time | New time interval for timer.

## operator=() [3/3]

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

Parameters

  timer | New time interval for timer.

## Pause()

void PTimer::Pause | ( |  | ) |

Pause a running timer.

This differs from the `Stop()` function in that the timer may be resumed at the point that it left off. That is time is "frozen" while the timer is paused.

## Reset()

void PTimer::Reset | ( |  | ) |

Restart a timer continuing from the time it was initially.

## Resolution()

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".

## Resume()

void PTimer::Resume | ( |  | ) |

Restart a paused timer continuing at the time it was paused.

The time left at the moment the timer was paused is the time until the next call to the notification function.

## RunContinuous()

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.

## SetInterval()

virtual void PTimer::SetInterval | ( | PInt64 | milliseconds = `0`,
|  | long | seconds = `0`,
|  | long | minutes = `0`,
|  | long | hours = `0`,
|  | int | days = `0`
| ) |  |

virtual

Set the value of the time interval.

The time interval, in milliseconds, is the sum of all of the parameters. For example all of the following are equivalent:

                  SetInterval(120000)
                  SetInterval(60000, 60)
                  SetInterval(60000, 0, 1)
                  SetInterval(0, 60, 1)
                  SetInterval(0, 0, 2)

Parameters

  milliseconds | Number of milliseconds for interval.
  seconds | Number of seconds for interval.
  minutes | Number of minutes for interval.
  hours | Number of hours for interval.
  days | Number of days for interval.

Reimplemented from PTimeInterval.

## SetNotifier()

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.

## Stop()

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.

The wait flag indicates that the function should wait for the timeout callback to complete before returning. That way external logic can be assured there is no race condition. However, under some circumstances this can cause a deadlock if the timeout function tries to acquire a mutex the calling thread already has, so an aysnchronouse version is provided. It is then the responsibility of the caller to handle the race condition with the timeout function.

## Tick()

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.

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

- timer.h