Yan's Website

Steadier chrono::steady_clock in C++

New

Saturday 29 March 2025

In C (on sensible OSes) we have access to a number of different clock identities (accessed via clock_gettime()) with significantly different characteristics. Three important ones are:

CLOCK_REALTIME

This is often the most suitable clock for general applications programming. The operating system tries to keep this clock in sync with UTC time.

Assuming that the system has NTP running, this will normally be within a few milliseconds from "true" UTC time and leap seconds will be accounted for (typically by smearing). It should not be affected by whatever time zone the machine happens to be in.

If you want to write some code which displays or records a time in a way that is relevant for humans and the most important thing is that each absolute date/time recorded or displayed is as close as possible to the true "wall-clock time", then this is the best clock to use.

Importantly, if you are writing code which performs scheduling (on a finer timescale than i.e. minutes) or otherwise relies on time values increasing monotonically or at a steady rate, this clock is problematic. Even though the OS and/or NTP implementation typically try to make adjustments to the clock by making frequency adjustments (and therefore gradually dragging the clock back into alignment) rather than making step changes, the calculations that implement this are susceptible to rounding errors, meaning that step changes in the order of microseconds (in either direction) can often be observed whenever NTP updates occur (commonly every 30 minutes or so).

So, despite the name, this clock is probably the least useful for what we might call "realtime programming".

In C++, the std::chrono::system_clock provides access to something with the behaviour described above (although whether it is derived from CLOCK_REALTIME is dependent on the standard library implementation and OS; it may be based on a similar but lower-resolution clock).

CLOCK_MONOTONIC

This is usually the most suitable clock for programming that involves either measuring durations or scheduling events with sub-second precision, or in any other case where the code relies on the assumption that the reported time can never "go backwards" from one call to the next.

The system does not attempt to ensure that the absolute value of this clock has any connection to UTC time (or any other "wall clock" time). The "epoch" for this clock is unspecified (however, in practice, on Linux it starts counting from zero when the machine boots). It is primarily intended for measuring durations, so the absolute value at any point in time shouldn't matter.

In C++, the std::chrono::steady_clock is intended to provide something with the behaviour of CLOCK_MONOTONIC. On Linux, with recent c++ standard library implementations, it is implemented on top of CLOCK_MONOTONIC.

So far, this sounds promising and it seems like CLOCK_MONOTONIC or steady_clock should be exactly what we want for "realtime programming". There are, however, a couple of pitfalls. For historical reasons, CLOCK_MONOTONIC is implemented on top of CLOCK_REALTIME (in Linux). i.e., the monotonic value is found by taking something like the realtime value (or a pre-cursor to it) and subtracting an offset. Whenever something like NTP updates the realtime clock, the offset for the monotonic clock has to be updated at the same time to maintain the illusion of monotonicity. There are two problems with this:

1. The above is clearly prone to bugs and indeed there have been bugs in this area over the years. Even on relatively recent kernel versions I have seen occasions when CLOCK_MONOTONIC appeared to jump near the time of an NTP update.
2. This means that the rate or frequency of CLOCK_MONOTONIC is still tied to the rate of CLOCK_REALTIME (and is therefore adjusted in response to NTP updates).

As a result, there are some (albeit uncommon) situations where CLOCK_MONOTONIC still doesn't cut it. Those situations are:

1. If it's absolutely crucial that a piece of code has code has access to a clock that never jumps backwards or forwards by an irregular amount even on the scale of nanoseconds or smaller.
2. If it's critical that the rate of the clock varies gradually rather than sharply (i.e. if the rate of change of the rate of change is small).

For these cases, since Linux 2.6.28, we have CLOCK_MONOTONIC_RAW.

CLOCK_MONOTONIC_RAW

In the context of C/C++/POSIX, CLOCK_MONOTONIC_RAW is the new and exotic option, but from an embedded/systems/hardware perspective it is actually the simplest to explain. This provides access to a clock which is derived as directly as possible from whatever hardware counter is available, which should be totally immune to any influence from software trying to correct or synchronise the time.

This solves the problems described above for CLOCK_MONOTONIC in certain uncommon use cases. CLOCK_MONOTONIC_RAW will not have a constant frequency, but its frequency is very likely to be proportional to the temperature of some crystal within the machine, and the thermal mass connected to that crystal is likely to result in the clock frequency changing much more gradually than the sharp changes in frequency seen on CLOCK_MONOTONIC due to NTP disciplining.

Of course, nothing is free. The down-sides of CLOCK_MONOTONIC_RAW are (A) potential slower access times and (B) potential coarser precision. Both are consequences of the clock being derived directly from hardware, and therefore may vary from one machine to another for the same code and OS.

Nonetheless, CLOCK_MONOTONIC_RAW is a very useful option to have and I have found it to be the least bad option for writing code which is itself implementing some sort of clock synchronisation routine (e.g. synchronising with a particular piece of hardware with its own clock over a network).

There are debates to be had about the definitions of "monotonic", "steady" etc and whether C++'s steady_clock should really be based on CLOCK_MONOTONIC_RAW rather than CLOCK_MONOTONIC on Linux, but for the time being if you find yourself needing a steadier steady clock in C++ and want to take advantage of std::chrono's algebraic approach to time units then you'll need this:

#include <chrono>
#include <ctime>

class RawClock
{
  public:
    using duration = std::chrono::nanoseconds;
    using rep = duration::rep;
    using period = duration::period;
    using time_point = std::chrono::time_point<RawClock>;

    // Whether RawClock should be steady is uncertain. It probably meets the
    // definition (as much as steady_clock does) but it also probably makes
    // sense to have only one of them declared as steady.
    static constexpr bool is_steady = false;

    static time_point now() noexcept
    {
        struct timespec ts;
        clock_gettime(CLOCK_MONOTONIC_RAW, &ts);

        duration sec = std::chrono::seconds{ts.tv_sec};
        duration nsec = std::chrono::nanoseconds{ts.tv_nsec};

        return time_point{sec + nsec};
    }
};