Timer

Overview

The Tsentry timer libraries encompass basic timer functions that can be used inside any application task to set and test timers.

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.

StartTimer & CurTimer

TIMERVAL StartTimer()
TIMERVAL CurTimer();

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

WallTime

TIMERVAL WallTime()

Returns the current value of the wall clock.

CurTimers

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.

IsSetTimer

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.

IsWallTime

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.

ResetTimer

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.

SetTimerToWallTime

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.

WallTimeToSetTimer

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.

TimerValToFileTime

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.

FileTimeToTimerVal

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.

SetUTimer, SetMTimer, & SetSTimer

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.

WallUTimer, WallMTimer, & WallSTimer

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.

AddUTimer, AddMTimer, & AddSTimer

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.

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

TstTimer

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:

// 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);

ExpUTimer, ExpMTimer, & ExpSTimer

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:

// Get the current time
TIMERVAL timer = StartTimer();

// Do some work
...

// Check if more than 100 ms has elapsed
int tstatus = ElapMTimer(timer, 100);

ActUTimer, ActMTimer, & ActSTimer

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:

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

ElapUTimer, ElapMTimer, & ElapSTimer

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.

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

RemUTimer, RemMTimer, & RemSTimer

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.

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

DiffUTimer, DiffMTimer, & DiffSTimer

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.

Timer Libraries