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.

TIMERVAL StartTimer()
TIMERVAL CurTimer();

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

TIMERVAL WallTime()

Returns the current value of the wall clock.

Timer Type Detection

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

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.

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.

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.

TIMERVAL value = WallTime(timer)
   where:
      TIMERVAL timer = Timer value

Converts a set interval timer to a wall clock time adjusting the current wall time by the amount of time elapsed since (or until) the passed 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.

Setting Timers

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

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.

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.

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

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

TIMERVAL value = AddSTimer(timer, 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.

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

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

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

int value = ExpSTimer(timer, 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);

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

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

int value = ActSTimer(timer, 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.

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

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

int64_t elap = ElapSTimer(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.

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

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

int64_t rem = RemSTimer(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.

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

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

int64_t delta = DiffSTimer(timer1, 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.