[Documentation] [TitleIndex] [WordIndex


This provides a portable set of time functions that are especially useful for porting other code or being wrapped by higher level c++ classes. Code has been divided broadly via a set of cmake probes into the following groups:

   2 - ECL_HAS_MACH_TIMERS - apple operating systems.
   4 - ECL_HAS_POSIX_TIMERS - the fallback posix functions when -lrt is not available.

Compiling & Linking

   1 #include <ecl/time_lite.hpp>
   3 // The portable time functions.
   4 using ecl::time_lite::sleep;
   5 using ecl::time_lite::sleep_until;
   6 using ecl::time_lite::epoch_time;
   8 // Platform specific function (requires linking to -lrt).
   9 using ecl::time_lite::cpu_time;

If outside ros, you will also need to link to ecl_time_lite.


Time Functions

The function epoch_time is often not exactly epoch time (i.e. secs from 1970), but dependant on your platform. Nonetheless, it always provides a relative timer measuring in sec/nsecs. Note that the time is only guaranteed to be monotonic (i.e. it won't jump) if cmake has defined the ECL_HAS_CLOCK_MONOTONIC macro.

The function cpu_time which is the amount of time that the process has actually spent executing on the cpu. This is sometimes useful for benchmarking tests.

Error Handling

Use with the TimeError (an extension of ecl_errors's Error handler) that provides time function specific verbose error messages.

   1 ecl::TimeStructure duration;
   2 duration.tv_sec = 1;
   3 duration.tv_nsec = 300000000;
   4 ecl::TimeError error = ecl::sleep(duration);
   5 if ( error.flag() != ecl::NoError) {
   6      std::cout << error.what() << std::endl;
   7      // do something
   8 }


The cmake detection scripts configure the header ecl/time_lite/config.hpp with many macros that describe your platform and also your time implementation in detail (particularly with posix, there are alot of levels and optionally available api). These are mostly for internal purposes, but may be useful to the user.

   1 #ifdef ECL_HAS_CPUTIME
   2   ecl::TimeStructure time;
   3   ecl::TimeError error = ecl::cpu_time(time);
   4   if ( error.flag() == ecl::NoError) {
   5     // benchmarking code result printout
   6   }
   7 #endif


2024-06-15 12:55