Please ask about problems and questions regarding this tutorial on answers.ros.org. Don't forget to include in your question the link to this page, the versions of your OS & ROS, and also add appropriate tags.

Timestamps and Durations

Timestamps

On a posix system, the timestamp class can be used to capture the current time. It does this using the MONOTONIC_CLOCK which calculates the time since the cpu was turned on. It has the advantage in that you are guaranteed that the clock will never jump backwards to correct for drift which is imperative for control systems running high frequency loops.

It can be also used just to store a time/duration in a convenient structure.

Initialising

   1 TimeStamp time_system;           // Automatically captures system time since Epoch.
   2 TimeStamp time_double(3.21)      // Initialise with a decimalised time (slow).
   3 TimeStamp time_pair(3,210000000) // Initialise with a (s,ns) pair (fast for posix rt systems).
   4 

These operations can also be performed to set the timestamp after construction:

   1 time_system.stamp();         // Automatically captures system time since Epoch.
   2 time_double.stamp(3.21)      // Initialise with a decimalised time (slow).
   3 time_pair.stamp(3,210000000) // Initialise with a (s,ns) pair (fast for posix rt systems).
   4 

All the usual comparison (==,!=,<=,>=,<,>) and mathematical (+,-,+=,-=) operations can also be used.

   1 if ( time_system > time_double ) {
   2     time_system -= time_double;
   3 }

Streaming:

   1 TimeStamp timestamp; // captures current time
   2 std::cout << timestamp << std::endl; // 1682346.235653090
   3 

Caution: The only thing to be wary of with timestamps is to remember that they must always be positive. This was a design decision that keeps the timestamp class as light as possible. If negativity was introduced, an extra sign bit would be required, and in almost all timestamp operations, this is not necessary.

Exceptions: The timestamp class will throw exceptions (in debug mode only) whenever a timestamp method is used that would create a negative timestamp.

Durations

Durations are intended to intuitively represent the passage of time. Although is is conceptually different from a timestamp, the functionality under the hood is currently identical. Subsequently, the ecl::TimeStamp class is currently typedef'd to the ecl::Duration class.

This might change at some point in the future if we require negativity (as mentioned above).