Timing utilities are very dependent on the system api provided for their use. This package provides a means for handling different timing models.
Posix timers record times as a pair : (seconds,nanoseconds), so they have a very fine resolution, but it needs to remembered that the system latency will still affect their results. For example, sleeping for 1nanosecond wont work as you expect, since the system latency will usually mean the command has to wait for the scheduler to grant it a slice of the action (usually a wait of around 1ms on a linux desktop). This latency is usually configured by the scheduler being used by the kernel. Returning to the pair, the first unit, seconds is usually of a system defined type. This allows it to be extendable to a larger type in the future if the system time requires a larger value. The latter is measured with the long variable, which is more than sufficient to cater for 1x10^9 units.
MacOSX timers are mostly posix, however they are missing the extensions provided by the librt library, e.g. clock_gettime and clock_nanosleep. The real downside of this is that it is not possible to use absolute time with the macosx posix timers (i.e. periodic timers will drift). There are another set of mac specific timers that will let you do this, but it has not yet been implemented.
I haven't yet implemented these.
Include the following at the top of any translation unit that uses time functions or classes.
You will also need to link to -lecl_time.
Timestamps provide a means of doing one of two things: - Recording the system time since some reference point. - Manually recording a timestamp, or time duration (e.g. result of a timestamp difference operation). There are several ways of initialising the timestamp:
These operations can also be performed to set the timestamp after construction:
All the usual comparison (==,!=,<=,>=,<,>) and mathematical (+,-,+=,-=) operations can also be used.
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 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 @ref ecl::TimeStamp "Timestamp" class is currently typedef'd to the @ref ecl::Duration "Duration" class. This might change at some point in the future if we require negativity (as mentioned above).
This is a fairly intuitive class and uses the TimeStamp class under the hood for recording times. Note that the stopwatch starts automatically, just use restart() if you wish to reset and start again.
This is a variation of the stopwatch for systems with librt. The time measured by the cpu watch is not system time, rather the time spent by the process actually exeucting on the cpu. This is very useful for benchmarking programs. Usage is exactly the same as for the stopwatch.
Some simple sleep classes. They can be used directly or preconfigured.
Snooze is a periodic sleeper, useful in control loops where you want to exactly control the time taken by each loop. Using a regular sleep function to do this can cause some time drift problems (refer to the snooze class documentation for more detail). The snooze class gets around this by setting its periodic timestamps off the absolute clock time rather than calculating relative time splits.
Note, this can be problematic if the periodic timestamps get behind the current time. To remedy this, by default the class validates the timestamp at each check and syncs it with the current time if it starts to lag behind (can easily be caused by the system scheduler knocking it out of whack in favour of another process). This can be manually turned off in the constructor if you're confident of the timing processes and this will marginally reduce the snoozer's latency.
This is a benchmarking utility for storing timings and then analysing them with some statistical methods.
- src/test/cpuwatch_rt.cpp - src/test/sleep.cpp - src/test/snooze.cpp - src/test/stopwatch.cpp - src/test/timestamp.cpp - src/test/time_data.cpp
- /ecl_core_apps/src/benchmarks/snooze.cpp : benchmarks the latencies for the periodic timer.
- @ref changelog "ChangeLog"
The cross-platform support, particularly the macosx absolute timers really needs to be done.