Timer

Table of Contents

Overview

The Tsentry timer libraries encompass basic timer functions . These functions may be called by that can be used inside any application task to set and test timers. The timer values are allocated and maintained in user defined variables and are tested by user calls.

Expand

title	Overview

These functions

Expand

title	Class Interface

The following public functions are provided as part of the tpriTimer support:

TIMERVAL SetUTimer (int us);
Return the value of a timer that will expire in 'us' microseconds.
If us = 0, turn timer off

TIMERVAL SetMTimer (int ms);
Return the value of a timer that will expire in 'ms' milliseconds.
If ms = 0, turn timer off

TIMERVAL SetSTimer (int s);
Return the value of a timer that will expire in 's' seconds.
If s = 0, turn timer off

TIMERVAL AddUTimer (TIMERVAL timer, int us);
Return the value of a timer that is set to expire 'us' microseconds after (if 'us' is positive) or before (if 'us' is negative) the timer value passed in 'timer'. The current passed 'timer' may be scheduled to expire in the future or may have already expired. If 'timer' is off (inactive), set the timer to expire 'us' microseconds into the future.

TIMERVAL AddMTimer (int ms);
Return the value of a timer that is set to expire 'ms' milliseconds after (if 'ms' is positive) or before (if 'ms' is negative) the timer value passed in 'timer'. The current passed 'timer' may be scheduled to expire in the future or may have already expired. If 'timer' is off (inactive), set the timer to expire 'us' microseconds into the future.

TIMERVAL AddSTimer (int s);
Return the value of a timer that is set to expire 's' seconds after (if 's' is positive) or before (if 's' is negative) the timer value passed in 'timer'. The current passed 'timer' may be scheduled to expire in the future or may have already expired. If 'timer' is off (inactive), set the timer to expire 'us' microseconds into the future.

__int64 RemUTimer (TIMERVAL timer);
Return the value of the time in microseconds remaining on timer 'timer'. If the timer has already expired, return the number of microseconds in the past as a negative number. If the timer is off (inactive), return a value of zero.

TIMERVAL AddMTimer (int ms);
Return the value of the time in milliseconds remaining on timer 'timer'. If the timer has already expired, return the number of milliseconds in the past as a negative number. If the timer is off (inactive), return a value of zero.

TIMERVAL AddSTimer (int s);
Return the value of the time in seconds remaining on timer 'timer'. If the timer has already expired, return the number of seconds in the past as a negative number. If the timer is off (inactive), return a value of zero

int TstTimer(TIMERVAL timer);
Test for current status of the timer 'timer'
Return value as as follows:
+1 = Timer still active and not timed out yet
0 = Timer is off (inactive)
-1 = Timer has timed out

Timer Types

There are two types of timers covered by these libraries: wall clock timers and set interval timers.

Wall clock timer values refer to an absolute date and time according to the host system. These timers are useful for timestamping events for HMI display or long-term storage. However, because these timers are referenced to the wall clock, which can be adjusted forwards and backwards either abruptly by an administrator or slowly by time synchronization services, these timers are not well suited for reliably measuring intervals of time. In other words, when comparing two wall clock timer values measured at two different moments, the numerical difference between the timer values may not equal the true time elapsed between the two measurements because the wall clock may have been adjusted faster or slower (or even backwards!) in between the two samples.

On the other hand, set interval timer values are based on a clock that ticks at very precise intervals. As a result, the underlying timer values increment at a constant rate regardless of any adjustments made to the system time. However, the underlying clock tick interval is not exactly an integer number of nanoseconds – for instance, the actual elapsed time between ticks on a given system could be 100.001 ns, and there is no compensation for this extra 0.001 ns. So while these set interval timer values are reliable for measuring short durations, over long durations these 0.001 ns errors can add up. As a result, measuring time across a day or more using a set interval timer may indicate an elapsed time that differs from the same measured by a wall clock timer by +/-1 second or more.

Timer Values

Within C/C++ tasks, all timers are stored as TIMERVAL variable types. Internally the TIMERVAL is a 64-bit integer counting 100ns increments, but applications should consider TIMERVAL as an opaque type and only utilize the methods described below for interacting with TIMERVAL variables.

Timer Functions

Current Time

The following functions can be used to get the current value of a timer.

Expand

title	StartTimer & CurTimer

Code Block
TIMERVAL StartTimer() TIMERVAL CurTimer();

These functions return the current value of the set interval timer clock. The two functions are identical.

Expand

title	WallTime

Code Block
TIMERVAL WallTime()

Returns the current value of the wall clock.

Expand

title	CurTimers

Code Block
void CurTimers(TIMERVAL* pSetTimer, TIMERVAL* pWallTime) where: TIMERVAL* pSetTimer = Pointer to output set interval time TIMERVAL* pWallTime = Pointer to output wall clock time

This function fills the passed timers with the current values of each type of timer. This function is provided to guarantee the timers are always sampled in the same order in situations where the values of both current timers are required.

Timer Type Detection

The following functions can be used to determine the type of a timer.

Expand

title	IsSetTimer

Code Block
int IsSetTimer(TIMERVAL timer) where: TIMERVAL timer = Timer value

Checks if the passed timer is a set interval timer value. If so, this function returns non-zero; otherwise it returns zero.

Expand

title	IsWallTime

Code Block
int IsWallTime(TIMERVAL timer) where: TIMERVAL timer = Timer value

Checks if the passed timer is a wall clock timer value. If so, this function returns non-zero; otherwise it returns zero.

Timer Reset

The following functions can be used to initialize or reset a timer.

Expand

title	ResetTimer

Code Block
TIMERVAL ResetTimer()

Returns a value indicating that the timer is reset.

Timer Type Conversion

The following functions can be used to convert between timer types.

Expand

title	SetTimerToWallTime

Code Block
TIMERVAL value = SetTimerToWallTime(TIMERVAL timer) where: TIMERVAL timer = Timer value

Converts a set interval timer to a wall clock time by offsetting the current wall time by the amount of time elapsed since (or until) the supplied set interval timer. Note this may differ from the wall time that would have been current at the moment that the set interval timer was set.

If the passed value is already a wall clock time, then it is returned unchanged.

Expand

title	WallTimeToSetTimer

Code Block
TIMERVAL value = WallTimeToSetTimer(TIMERVAL timer) where: TIMERVAL timer = Timer value

Converts a wall clock timer to a set interval timer by offsetting the current set interval clock time by the amount of time elapsed since (or until) the supplied wall time. Note this may differ from the set interval timer value that would have been current at the moment that the wall clock value was retrieved.

If the passed value is already a set interval timer, then it is returned unchanged.

Expand

title	TimerValToFileTime

Code Block
TIMERVAL value = TimerValToFileTime(TIMERVAL timer, LPFILETIME pFileTime) where: TIMERVAL timer = Timer value LPFILETIME pFileTime = Pointer to target FILETIME structure

Converts a timer to a FILETIME structure. If the supplied timer is a set interval timer, then it is first converted to a wall clock time before converting to a FILETIME.

Expand

title	FileTimeToTimerVal

Code Block
TIMERVAL value = FileTimeToTimerVal(LPFILETIME pFileTime) where: LPFILETIME pFileTime = Pointer to target FILETIME structure

Converts a FILETIME to a wall clock timer.

Setting Timers

The following functions can be used to create a timer that will expire at some time in the future.

Expand

title	SetUTimer, SetMTimer, & SetSTimer

Code Block

TIMERVAL value = SetUTimer(us)
   where:
      int64_t us = Timeout value (us)

TIMERVAL value = SetMTimer(ms)
   where:
      int64_t ms = Timeout value (ms)

TIMERVAL value = SetSTimer(sec)
   where:
      int64_t sec = Timeout value (sec)

Creates a set interval timer set to expire after a duration specified in microseconds, milliseconds, or seconds.

Expand

title	WallUTimer, WallMTimer, & WallSTimer

Code Block

TIMERVAL value = WallUTimer(us)
   where:
      int64_t us = Timeout value (us)

TIMERVAL value = WallMTimer(ms)
   where:
      int64_t ms = Timeout value (ms)

TIMERVAL value = WallSTimer(sec)
   where:
      int64_t sec = Timeout value (sec)

Creates a wall clock timer set to expire after a duration specified in microseconds, milliseconds, or seconds.

Expand

title	AddUTimer, AddMTimer, & AddSTimer

Code Block

TIMERVAL value = AddUTimer(TIMERVAL timer, int64_t us)
   where:
      TIMERVAL timer = Existing timer
      int64_t us = Timeout value (us)

TIMERVAL value = AddMTimer(TIMERVAL timer, int64_t ms)
   where:
      TIMERVAL timer = Existing timer
      int64_t ms = Timeout value (ms)

TIMERVAL value = AddSTimer(TIMERVAL timer, int64_t sec)
   where:
      TIMERVAL timer = Existing timer
      int64_t sec = Timeout value (sec)

Adds additional time to an existing timer and returns the new timer value. This function can be used to allow a timer to expire on fixed intervals without concern for delays between when the timer actually expires and when the timer is checked.

Code Block

// Set a timer to expire after 100 ms
TIMERVAL timer = SetMTimer(100);

// Oversleep past the timer's expiration
Sleep(115);

// Reset the timer so that it will now expire 200 ms
// after it was originally set (not 100 ms from now)
timer = AddMTimer(timer, 100);

This function works with both wall clock timers and set interval timers. If the timer value passed to the AddXTimer(..) function has not previously been set then the returned timer will be a set interval timer set to expire after the specified timeout.

Testing Timer Status

The following functions can be used to test if a timer is active or expired.

Expand

title	TstTimer

Code Block
int TstTimer(TIMERVAL timer) where: TIMERVAL timer = Existing timer

Compares a timer value against the current time:

+1 = Timer has not yet expired i.e. the current time is after the timer value
-1 = Timer has expired i.e. the current time is before the timer value
0 = The timer value has not been set

This function works with both wall clock timers and set interval timers and is typically used in conjunction with the SetXTimer(..) or WallXTimer(..) methods:

Code Block
// Set a timer to expire after 100 ms TIMERVAL timer = SetMTimer(100); // Do some work ... // Check if the timer has expired int tstatus = TstTimer(timer);

Expand

title	ExpUTimer, ExpMTimer, & ExpSTimer

Code Block

int value = ExpUTimer(TIMERVAL timer, int64_t us)
   where:
      TIMERVAL timer = Timer to test
      int64_t us     = Timeout value (us)

int value = ExpMTimer(TIMERVAL timer, int64_t ms)
   where:
      TIMERVAL timer = Timer to test
      int64_t ms     = Timeout value (ms)

int value = ExpSTimer(TIMERVAL timer, int64_t sec)
   where:
      TIMERVAL timer = Timer to test
      int64_t sec    = Timeout value (sec)

Tests if a timer has expired i.e. the time elapsed since a timer was set is greater than or equal to a timeout. If so, this function returns non-zero. Zero is returned if the timeout hasn’t been reached or if the timer has not been set.

This function works with both wall clock timers and set interval timers and is typically used in conjunction with the StartTimer() or WallTime() methods:

Code Block
// Get the current time TIMERVAL timer = StartTimer(); // Do some work ... // Check if more than 100 ms has elapsed int tstatus = ElapMTimer(timer, 100);

Expand

title	ActUTimer, ActMTimer, & ActSTimer

Code Block

int value = ActUTimer(TIMERVAL timer, int64_t us)
   where:
      TIMERVAL timer = Timer to test
      int64_t us     = Timeout value (us)

int value = ActMTimer(TIMERVAL timer, int64_t ms)
   where:
      TIMERVAL timer = Timer to test
      int64_t ms     = Timeout value (ms)

int value = ActSTimer(TIMERVAL timer, int64_t sec)
   where:
      TIMERVAL timer = Timer to test
      int64_t sec    = Timeout value (sec)

Tests if a timer is still active i.e. the time elapsed since a timer was set is less than a timeout. If so, this function returns non-zero. Zero is returned if the timeout has already been reached or if the timer has not been set.

This function works with both wall clock timers and set interval timers and is typically used in conjunction with the StartTimer() or WallTime() methods:

Code Block
// Get the current time TIMERVAL timer = StartTimer(); // Do some work ... // Check if less than 100 ms has elapsed int tstatus = ActMTimer(timer, 100);

Elapsed Time

The following functions can be used to calculate the time elapsed since a timer value.

Expand

title	ElapUTimer, ElapMTimer, & ElapSTimer

Code Block

int64_t elap = ElapUTimer(TIMERVAL timer)
   where:
      TIMERVAL timer = Timer to test

int64_t elap = ElapMTimer(TIMERVAL timer)
   where:
      TIMERVAL timer = Timer to test

int64_t elap = ElapSTimer(TIMERVAL timer)
   where:
      TIMERVAL timer = Timer to test

Calculates the amount of time elapsed since a timer value, returned in units of full microseconds, milliseconds, or seconds. These functions will return zero for the first full unit of time after a timer is set, then count +1 for each successive time unit thereafter.

Code Block

// Get the current time
TIMERVAL timer = StartTimer();
// For the next 1 second, ElapSTimer(..) will return 0
// For the 1 second after that, RemSTimer(..) will return 1
// For the 1 second after that, RemSTimer(..) will return 2
// etc.

These functions work with both wall clock timers and set interval timers.

If the timer is reset, then these functions will return zero.

Remaining Time

The following functions can be used to calculate the time remaining until a timer value.

Expand

title	RemUTimer, RemMTimer, & RemSTimer

Code Block

int64_t rem = RemUTimer(TIMERVAL timer)
   where:
      TIMERVAL timer = Timer to test

int64_t rem = RemMTimer(TIMERVAL timer)
   where:
      TIMERVAL timer = Timer to test

int64_t rem = RemSTimer(TIMERVAL timer)
   where:
      TIMERVAL timer = Timer to test

Calculates the amount of time remaining until a timer value, returned in units of full microseconds, milliseconds, or seconds. These functions will count down as the current time approaches the timer value, reaching zero at the instant that the current time equals the timer value. For the time unit after the timer expires (e.g. the first second), the return value will remain zero, and after that continue to count negative.

Code Block

// Set a timer for 3 seconds in the future
TIMERVAL timer = SetSTimer(3);
// For the next 1 second, RemSTimer(..) will return 3
// For the 1 second after that, RemSTimer(..) will return 2
// For the 1 second after that, RemSTimer(..) will return 1
// At this moment the timer expires
// For the next 1 second, RemSTimer(..) will return 0
// For the next 1 second, RemSTimer(..) will return -1
// For the next 1 second, RemSTimer(..) will return -2
// etc.

These functions work with both wall clock timers and set interval timers.

If the timer is reset, then these functions will return zero.

Calculating Time Differences

The following functions can be used to calculate the difference between two timer values.

Expand

title	DiffUTimer, DiffMTimer, & DiffSTimer

Code Block

int64_t delta = DiffUTimer(TIMERVAL timer1, TIMERVAL timer2)
   where:
      TIMERVAL timer1  = First timer
      TIMERVAL timer2  = Second timer

int64_t delta = DiffMTimer(TIMERVAL timer1, TIMERVAL timer2)
   where:
      TIMERVAL timer1  = First timer
      TIMERVAL timer2  = Second timer

int64_t delta = DiffSTimer(TIMERVAL timer1, TIMERVAL timer2)
   where:
      TIMERVAL timer1  = First timer
      TIMERVAL timer2  = Second timer

Calculates the difference between two timers (timer1 - timer2), returned in units of full microseconds, milliseconds, or seconds.

These functions work with both wall clock timers and set interval timers. If the two timers are of different types, the functions convert the set interval timer to a wall clock timer before calculating the difference.

If either timer is reset, then these functions will return zero.

Versions Compared

Old Version 1

New Version Current

Key

Overview

Timer Types

Timer Values

Timer Functions

Current Time

Timer Type Detection

Timer Reset

Timer Type Conversion

Setting Timers

Testing Timer Status

Elapsed Time

Remaining Time

Calculating Time Differences

Page Comparison

Versions Compared

Old Version 1

New Version Current

Key

Overview

Timer Types

Timer Values

Timer Functions

Current Time

Timer Type Detection

Timer Reset

Timer Type Conversion

Setting Timers

Testing Timer Status

Elapsed Time

Remaining Time

Calculating Time Differences