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.

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.

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

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.

Timer Type Conversion

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

Setting Timers

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

Testing Timer Status

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

Elapsed Time

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

Remaining Time

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

Calculating Time Differences

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

Timer Libraries