[Chrono][Darwin] On Darwin use CLOCK_UPTIME_RAW instead of CLOCK_MONOTONIC

[bruno]

Summary

CLOCK_MONOTONIC is only defined on Darwin on libc versions >= 1133 and its behaviour differs from Linux. CLOCK_UPTIME on Darwin actually matches
CLOCK_MONOTONIC on Linux, due to historical coincidence (Linux doesn't match POSIX here but Darwin does). Use CLOCK_UPTIME_RAW on Darwin since the _RAW version gives nanosecond precision and is lower overhead.

[EricWF]

I'm not sure CLOCK_UPTIME_RAW meets the requirements of steady_clock. The manpage for clock_gettime on OS X specifies CLOCK_UPTIME_RAW as:

CLOCK_UPTIME_RAW clock that increments monotonically, in the same manner as CLOCK_MONOTONIC_RAW, but that does not increment while the system is asleep.

And C++17 [time.clock.steady]p1 says:

Objects of class steady_clock represent clocks for which values of time_point never decrease as physical time advances and for which values of time_point advance at a steady rate relative to real time. That is, the clock may not be adjusted.

So if CLOCK_UPTIME_RAW doesn't update while the system is asleep does it advance at a steady rate relative to real time? I'm not convinced it does.

@mclow.lists Do you agree with this interpretation?

[mclow.lists]

I agree with @EricWF . If CLOCK_UPTIME_RAW doesn't meet the requirements of steady_clock (i.e, monotonically increasing, and advances in real time), then we can't use it.

[EricWF]

CLOCK_MONOTONIC_RAW however seems to meet the requirements..

[howard.hinnant]

I would like to offer two thoughts:

1. Timing with steady_clock is often used to time very short events. It should be respected as the "high_resolution_clock". This means that two consecutive calls to steady_clock::now() should return nanoseconds resolution and should not be equal unless the implementation is actually able to complete a call to steady_clock::now() in less than 1ns.

2. Here's test of thought 1:

#include <chrono>
#include <time.h>
#include <errno.h>
#include <sys/sysctl.h>

std::chrono::milliseconds
uptime()
{
    using namespace std::chrono;
    timeval ts;
    auto ts_len = sizeof(ts);
    int mib[2] = { CTL_KERN, KERN_BOOTTIME };
    auto constexpr mib_len = sizeof(mib)/sizeof(mib[0]);
    if (sysctl(mib, mib_len, &ts, &ts_len, nullptr, 0) == 0)
    {
        system_clock::time_point boot{seconds{ts.tv_sec} + microseconds{ts.tv_usec}};
        return duration_cast<milliseconds>(system_clock::now() - boot);
    }
    return 0ms;
}

std::chrono::nanoseconds
get_uptime_raw()
{
    using namespace std::chrono;
    struct timespec tp;
    clock_gettime(CLOCK_UPTIME_RAW, &tp);
    return seconds(tp.tv_sec) + nanoseconds(tp.tv_nsec);
}

std::chrono::nanoseconds
get_monotonic()
{
    using namespace std::chrono;
    struct timespec tp;
    clock_gettime(CLOCK_MONOTONIC, &tp);
    return seconds(tp.tv_sec) + nanoseconds(tp.tv_nsec);
}

#include "date.h"
#include <iostream>

template <class Duration>
void
display(Duration time)
{
    using namespace date;
    auto d = floor<days>(time);
    time -= d;
    std::cout << d.count() << " days " << make_time(time) << '\n';
}

int
main()
{
    using namespace std::chrono;
    for (int i = 0; i < 4; ++i)
    {
        std::cout << i << '\n';
        {
            auto t0 = uptime();
            auto t1 = uptime();
            std::cout << "boot time                     : ";  display(t0);
            std::cout << "boot time                     : ";  display(t1);
            std::cout << "delta boot time               : " << nanoseconds{t1 - t0}.count() << "ns\n";
        }
        {
            auto t0 = get_uptime_raw();
            auto t1 = get_uptime_raw();
            std::cout << "CLOCK_UPTIME_RAW              : "; display(t0);
            std::cout << "CLOCK_UPTIME_RAW              : "; display(t1);
            std::cout << "delta CLOCK_UPTIME_RAW time   : " << nanoseconds{t1 - t0}.count() << "ns\n";
        }
        {
            auto t0 = get_monotonic();
            auto t1 = get_monotonic();
            std::cout << "CLOCK_MONOTONIC               : "; display(t0);
            std::cout << "CLOCK_MONOTONIC               : "; display(t1);
            std::cout << "delta CLOCK_MONOTONIC time    : " << nanoseconds{t1 - t0}.count() << "ns\n";
        }
        {
            auto t0 = std::chrono::steady_clock::now().time_since_epoch();
            auto t1 = std::chrono::steady_clock::now().time_since_epoch();
            std::cout << "mach_absolute_time            : "; display(t0);
            std::cout << "mach_absolute_time            : "; display(t1);
            std::cout << "delta mach_absolute_time time : " << nanoseconds{t1 - t0}.count() << "ns\n";
        }
        std::cout << '\n';
    }
}

Sorry, it requires "date.h" from https://github.com/HowardHinnant/date . It is header-only and portable. It's just used for formatting purposes if it really stresses you out.

For me this outputs (at -O3):

Jade:~/Development/cljunk> a.out
0
boot time                     : 11 days 22:30:42.827
boot time                     : 11 days 22:30:42.827
delta boot time               : 0ns
CLOCK_UPTIME_RAW              : 11 days 22:22:28.960672112
CLOCK_UPTIME_RAW              : 11 days 22:22:28.960672266
delta CLOCK_UPTIME_RAW time   : 154ns
CLOCK_MONOTONIC               : 11 days 22:30:42.827318000
CLOCK_MONOTONIC               : 11 days 22:30:42.827318000
delta CLOCK_MONOTONIC time    : 0ns
mach_absolute_time            : 11 days 22:22:28.960714394
mach_absolute_time            : 11 days 22:22:28.960714504
delta mach_absolute_time time : 110ns

1
boot time                     : 11 days 22:30:42.827
boot time                     : 11 days 22:30:42.827
delta boot time               : 0ns
CLOCK_UPTIME_RAW              : 11 days 22:22:28.960761867
CLOCK_UPTIME_RAW              : 11 days 22:22:28.960761932
delta CLOCK_UPTIME_RAW time   : 65ns
CLOCK_MONOTONIC               : 11 days 22:30:42.827402000
CLOCK_MONOTONIC               : 11 days 22:30:42.827402000
delta CLOCK_MONOTONIC time    : 0ns
mach_absolute_time            : 11 days 22:22:28.960793667
mach_absolute_time            : 11 days 22:22:28.960793747
delta mach_absolute_time time : 80ns

2
boot time                     : 11 days 22:30:42.827
boot time                     : 11 days 22:30:42.827
delta boot time               : 0ns
CLOCK_UPTIME_RAW              : 11 days 22:22:28.960835164
CLOCK_UPTIME_RAW              : 11 days 22:22:28.960835227
delta CLOCK_UPTIME_RAW time   : 63ns
CLOCK_MONOTONIC               : 11 days 22:30:42.827476000
CLOCK_MONOTONIC               : 11 days 22:30:42.827476000
delta CLOCK_MONOTONIC time    : 0ns
mach_absolute_time            : 11 days 22:22:28.960867852
mach_absolute_time            : 11 days 22:22:28.960867944
delta mach_absolute_time time : 92ns

3
boot time                     : 11 days 22:30:42.827
boot time                     : 11 days 22:30:42.827
delta boot time               : 0ns
CLOCK_UPTIME_RAW              : 11 days 22:22:28.960911646
CLOCK_UPTIME_RAW              : 11 days 22:22:28.960911737
delta CLOCK_UPTIME_RAW time   : 91ns
CLOCK_MONOTONIC               : 11 days 22:30:42.827553000
CLOCK_MONOTONIC               : 11 days 22:30:42.827553000
delta CLOCK_MONOTONIC time    : 0ns
mach_absolute_time            : 11 days 22:22:28.960945129
mach_absolute_time            : 11 days 22:22:28.960945196
delta mach_absolute_time time : 67ns

3. Third thought (off by one errors are rampant! ;-) ):

CLOCK_MONOTONIC gives a more accurate report of system uptime, and thus more accurately respects the intent of steady_clock's definition. However the difference is slight. Only CLOCK_UPTIME_RAW and mach_absolute_time are able to time functions in the nanosecond range, which is the most important use case for steady_clock.

Imho, only CLOCK_UPTIME_RAW or mach_absolute_time are acceptable implementations of steady_clock on macOS. I feel strongly enough about this that I would like to see a static_assert that the CLOCK_MONOTONIC is never accidentally chosen by the preprocessor when targeting macOS, or iOS. I can't directly speak to other platforms. But I would like to see tests such as this applied to other platforms. steady_clock should be able to measure short events without returning 0ns. The Windows experience with <chrono> has taught us well that this would be a dissatisfying experience to customers.

[howard.hinnant]

One more comment: steady_clock::now() is not allowed to throw an exception because it shall satisfy the requirements of TrivialClock ([time.clock]/p1). And [time.clock.req]/p4/b4 says that a TrivialClock::now() does not throw exceptions.

[EricWF]

Howard Thank you for your excellent analysis. Although I still don't think that CLOCK_UPTIME_RAW meets the requirements of steady_clock but I would rather relax the standard here than provide a poor implementation.

In D27429#618998, @howard.hinnant wrote:

I feel strongly enough about this that I would like to see a static_assert that the CLOCK_MONOTONIC is never accidentally chosen by the preprocessor when targeting macOS, or iOS.

I agree. This patch LGTM after ensuring that CLOCK_MONOTONIC is never selected on Apple platforms.

[howard.hinnant]

Thanks Eric.

Fwiw CLOCK_MONOTONIC won't meet the requirements of the standard either. The standard appears to require steady_clock to be a perfect clock and there is no such thing. The wording used to only require monotonic, but the committee got a little too enthusiastic. :-)

[EricWF]

Marking as changes requested.

Please make sure we fall back to the old implementation on Apple platforms when CLOCK_UPTIME_RAW isn't available.

[bruno]

Thanks for the reviews. @howard.hinnant thanks for the great explanation & examples.

Attached a new version of the patch, addressing all suggestions. The logic became a bit simpler after Saleem's r290804, which already moved the CLOCK_MONOTONIC to be the last condition.

On top of that, I also conditionalized the presence of clock_gettime, which isn't available before 10.12 on macosx and specific versions on other apple platforms. Check that by looking at the deployment target.

[howard.hinnant]

src/chrono.cpp

218

Nice, thanks!

[bruno]

@EricWF ok to commit?

[EricWF]

In D27429#637507, @bruno wrote:

@EricWF ok to commit?

Yes sorry This LGTM. (I thought I had approved this yesterday, but I forgot to hit enter).

src/chrono.cpp

218

This code is currently dead due to the structure of the #ifdefs. However I think it's great documentation and great future proofing!

[bruno]

r291466 & r291517

src/chrono.cpp

 //===------------------------- chrono.cpp ---------------------------------===//
 //
 //                     The LLVM Compiler Infrastructure
 //
 // This file is dual licensed under the MIT and the University of Illinois Open
 // Source Licenses. See LICENSE.TXT for details.
 //
 //===----------------------------------------------------------------------===//
 
 #include "chrono"
 #include "cerrno"        // errno
 #include "system_error"  // __throw_system_error
 #include <time.h>        // clock_gettime, CLOCK_MONOTONIC and CLOCK_REALTIME
 
+#if (__APPLE__)
+#if defined(__ENVIRONMENT_MAC_OS_X_VERSION_MIN_REQUIRED__)
+#if __ENVIRONMENT_MAC_OS_X_VERSION_MIN_REQUIRED__ >= 101200
+#define _LIBCXX_USE_CLOCK_GETTIME
+#endif
+#elif defined(__ENVIRONMENT_IPHONE_OS_VERSION_MIN_REQUIRED__)
+#if __ENVIRONMENT_IPHONE_OS_VERSION_MIN_REQUIRED__ >= 100000
+#define _LIBCXX_USE_CLOCK_GETTIME
+#endif
+#elif defined(__ENVIRONMENT_TV_OS_VERSION_MIN_REQUIRED__)
+#if __ENVIRONMENT_TV_OS_VERSION_MIN_REQUIRED__ >= 100000
+#define _LIBCXX_USE_CLOCK_GETTIME
+#endif
+#elif defined(__ENVIRONMENT_WATCH_OS_VERSION_MIN_REQUIRED__)
+#if __ENVIRONMENT_WATCH_OS_VERSION_MIN_REQUIRED__ >= 30000
+#define _LIBCXX_USE_CLOCK_GETTIME
+#endif
+#endif // __ENVIRONMENT_.*_VERSION_MIN_REQUIRED__
+#else
+#define _LIBCXX_USE_CLOCK_GETTIME
+#endif // __APPLE__
+
 #if defined(_LIBCPP_WIN32API)
 #define WIN32_LEAN_AND_MEAN
 #define VC_EXTRA_LEAN
 #include <Windows.h>
 #if _WIN32_WINNT >= _WIN32_WINNT_WIN8
 #include <winapifamily.h>
 #endif
 #else

 #else
   GetSystemTimeAsFileTime(&ft);
 #endif
 
   filetime_duration d{(static_cast<__int64>(ft.dwHighDateTime) << 32) |
                        static_cast<__int64>(ft.dwLowDateTime)};
   return time_point(duration_cast<duration>(d - nt_to_unix_epoch));
 #else
-#ifdef CLOCK_REALTIME
+#if defined(_LIBCXX_USE_CLOCK_GETTIME) && defined(CLOCK_REALTIME)
     struct timespec tp;
     if (0 != clock_gettime(CLOCK_REALTIME, &tp))
         __throw_system_error(errno, "clock_gettime(CLOCK_REALTIME) failed");
     return time_point(seconds(tp.tv_sec) + microseconds(tp.tv_nsec / 1000));
-#else  // !CLOCK_REALTIME
+#else
     timeval tv;
     gettimeofday(&tv, 0);
     return time_point(seconds(tv.tv_sec) + microseconds(tv.tv_usec));
-#endif  // CLOCK_REALTIME
+#endif // _LIBCXX_USE_CLOCK_GETTIME && CLOCK_REALTIME
 #endif
 }
 
 time_t
 system_clock::to_time_t(const time_point& t) _NOEXCEPT
 {
     return time_t(duration_cast<seconds>(t.time_since_epoch()).count());
 }

 // Warning:  If this is not truly steady, then it is non-conforming.  It is
 //  better for it to not exist and have the rest of libc++ use system_clock
 //  instead.
 
 const bool steady_clock::is_steady;
 
 #if defined(__APPLE__)
 
+// Darwin libc versions >= 1133 provide ns precision via CLOCK_UPTIME_RAW
+#if defined(_LIBCXX_USE_CLOCK_GETTIME) && defined(CLOCK_UPTIME_RAW)
+steady_clock::time_point
+steady_clock::now() _NOEXCEPT
+{
+    struct timespec tp;
+    if (0 != clock_gettime(CLOCK_UPTIME_RAW, &tp))
+        __throw_system_error(errno, "clock_gettime(CLOCK_UPTIME_RAW) failed");
+    return time_point(seconds(tp.tv_sec) + nanoseconds(tp.tv_nsec));
+}
+
+#else
 //   mach_absolute_time() * MachInfo.numer / MachInfo.denom is the number of
 //   nanoseconds since the computer booted up.  MachInfo.numer and MachInfo.denom
 //   are run time constants supplied by the OS.  This clock has no relationship
 //   to the Gregorian calendar.  It's main use is as a high resolution timer.
 
 // MachInfo.numer / MachInfo.denom is often 1 on the latest equipment.  Specialize
 //   for that case as an optimization.
 

 }
 
 steady_clock::time_point
 steady_clock::now() _NOEXCEPT
 {
     static FP fp = init_steady_clock();
     return time_point(duration(fp()));
 }
+#endif // defined(_LIBCXX_USE_CLOCK_GETTIME) && defined(CLOCK_UPTIME_RAW)
 
 #elif defined(_LIBCPP_WIN32API)
 
 steady_clock::time_point
 steady_clock::now() _NOEXCEPT
 {
   static LARGE_INTEGER freq;
   static BOOL initialized = FALSE;
   if (!initialized)
     initialized = QueryPerformanceFrequency(&freq); // always succceeds
 
   LARGE_INTEGER counter;
   QueryPerformanceCounter(&counter);
   return time_point(duration(counter.QuadPart * nano::den / freq.QuadPart));
 }
 
 #elif defined(CLOCK_MONOTONIC)
 
+// On Apple platforms only CLOCK_UPTIME_RAW or mach_absolute_time are able to
+// time functions in the nanosecond range. Thus, they are the only acceptable
+// implementations of steady_clock.
+#ifdef __APPLE__
+#error "Never use CLOCK_MONOTONIC for steady_clock::now on Apple platforms"
+#endif
+
 steady_clock::time_point
 steady_clock::now() _NOEXCEPT
 {
     struct timespec tp;
     if (0 != clock_gettime(CLOCK_MONOTONIC, &tp))
         __throw_system_error(errno, "clock_gettime(CLOCK_MONOTONIC) failed");
     return time_point(seconds(tp.tv_sec) + nanoseconds(tp.tv_nsec));
 }