Delve into clock rabbit hole

The worst issue I had with consts.sh for clock_gettime is how it defined
too many clocks. So I looked into these clocks all day to figure out how
how they overlap in functionality. I discovered counter-intuitive things
such as how CLOCK_MONOTONIC should be CLOCK_UPTIME on MacOS and BSD, and
that CLOCK_BOOTTIME should be CLOCK_MONOTONIC on MacOS / BSD. Windows 10
also has some incredible new APIs, that let us simplify clock_gettime().

  - Linux CLOCK_REALTIME         -> GetSystemTimePreciseAsFileTime()
  - Linux CLOCK_MONOTONIC        -> QueryUnbiasedInterruptTimePrecise()
  - Linux CLOCK_MONOTONIC_RAW    -> QueryUnbiasedInterruptTimePrecise()
  - Linux CLOCK_REALTIME_COARSE  -> GetSystemTimeAsFileTime()
  - Linux CLOCK_MONOTONIC_COARSE -> QueryUnbiasedInterruptTime()
  - Linux CLOCK_BOOTTIME         -> QueryInterruptTimePrecise()

Documentation on the clock crew has been added to clock_gettime() in the
docstring and in redbean's documentation too. You can read that to learn
interesting facts about eight essential clocks that survived this purge.
This is original research you will not find on Google, OpenAI, or Claude

I've tested this change by porting *NSYNC to become fully clock agnostic
since it has extensive tests for spotting irregularities in time. I have
also included these tests in the default build so they no longer need to
be run manually. Both CLOCK_REALTIME and CLOCK_MONOTONIC are good across
the entire amd64 and arm64 test fleets.

Author: jart

libc/calls/BUILD.mk

@@ -48,12 +48,13 @@ LIBC_CALLS_A_DIRECTDEPS =				\
 	LIBC_NT_PDH					\
 	LIBC_NT_POWRPROF				\
 	LIBC_NT_PSAPI					\
+	LIBC_NT_REALTIME				\
 	LIBC_NT_SYNCHRONIZATION				\
 	LIBC_NT_WS2_32					\
 	LIBC_STR					\
 	LIBC_SYSV					\
 	LIBC_SYSV_CALLS					\
-	THIRD_PARTY_COMPILER_RT
+	THIRD_PARTY_COMPILER_RT				\
 
 LIBC_CALLS_A_DEPS :=					\
 	$(call uniq,$(foreach x,$(LIBC_CALLS_A_DIRECTDEPS),$($(x))))

libc/calls/clock_getres.c

@@ -20,36 +20,49 @@
 #include "libc/dce.h"
 #include "libc/intrin/describeflags.h"
 #include "libc/intrin/strace.h"
+#include "libc/runtime/clktck.h"
 #include "libc/sysv/consts/clock.h"
 #include "libc/sysv/errfuns.h"
 #include "libc/time.h"
 
-static int sys_clock_getres_poly(int clock, struct timespec *ts, int64_t real,
-                                 int64_t real_coarse, int64_t boot) {
-  ts->tv_sec = 0;
-  if (clock == CLOCK_REALTIME) {
-    ts->tv_nsec = real;
+static uint64_t hz_to_nanos(uint64_t frequency) {
+  if (!frequency)
     return 0;
-  } else if (clock == CLOCK_REALTIME_COARSE) {
-    ts->tv_nsec = real_coarse;
-    return 0;
-  } else if (clock == CLOCK_MONOTONIC) {
-    ts->tv_nsec = 10;
+  uint64_t quotient = 1000000000 / frequency;
+  uint64_t remainder = 1000000000 % frequency;
+  if (remainder > 0)
+    quotient += 1;
+  return quotient;
+}
+
+static int sys_clock_getres_poly(int clock, struct timespec *ts, int64_t prec) {
+  if (ts)
+    ts->tv_sec = 0;
+  if (clock == CLOCK_REALTIME ||   //
+      clock == CLOCK_BOOTTIME ||   //
+      clock == CLOCK_MONOTONIC ||  //
+      clock == CLOCK_MONOTONIC_RAW) {
+    if (ts)
+      ts->tv_nsec = prec;
     return 0;
-  } else if (clock == CLOCK_BOOTTIME) {
-    ts->tv_nsec = boot;
+  } else if (clock == CLOCK_REALTIME_COARSE ||
+             clock == CLOCK_MONOTONIC_COARSE ||
+             clock == CLOCK_THREAD_CPUTIME_ID ||
+             clock == CLOCK_PROCESS_CPUTIME_ID) {
+    if (ts)
+      *ts = timespec_fromnanos(hz_to_nanos(CLK_TCK));
     return 0;
   } else {
     return einval();
   }
 }
 
 static int sys_clock_getres_nt(int clock, struct timespec *ts) {
-  return sys_clock_getres_poly(clock, ts, 100, 1000000, 1000000);
+  return sys_clock_getres_poly(clock, ts, 100);
 }
 
 static int sys_clock_getres_xnu(int clock, struct timespec *ts) {
-  return sys_clock_getres_poly(clock, ts, 1000, 1000, 1000);
+  return sys_clock_getres_poly(clock, ts, 1000);
 }
 
 /**

libc/calls/clock_gettime-mono.c

@@ -18,42 +18,63 @@
 ╚─────────────────────────────────────────────────────────────────────────────*/
 #include "libc/atomic.h"
 #include "libc/calls/struct/timespec.h"
+#include "libc/calls/struct/timespec.internal.h"
+#include "libc/calls/struct/timeval.h"
 #include "libc/cosmo.h"
-#include "libc/errno.h"
+#include "libc/dce.h"
 #include "libc/nexgen32e/rdtsc.h"
-#include "libc/nexgen32e/x86feature.h"
 
 /**
- * @fileoverview Fast Monotonic Clock Polyfill for XNU/NT.
+ * @fileoverview Monotonic clock polyfill.
+ *
+ * This isn't quite `CLOCK_MONOTONIC` and isn't quite `CLOCK_BOOTTIME`
+ * either; however it is fast and almost always goes in one direction.
+ *
+ * Intel architecture guarantees that a mapping exists between rdtsc &
+ * nanoseconds only if the cpu advertises invariant timestamps support
+ * however this shouldn't matter for a monotonic clock since we really
+ * don't want to have it tick while suspended. Sadly that shall happen
+ * since nearly all x86 microprocessors support invariant tsc which is
+ * why we try to avoid this fallback when possible.
  */
 
+int sys_sysctl(int *, unsigned, void *, size_t *, void *, size_t) libcesque;
+
 static struct {
   atomic_uint once;
-  struct timespec base_wall;
-  uint64_t base_tick;
+  unsigned long base;
+  struct timespec boot;
 } g_mono;
 
+static struct timespec get_boot_time_xnu(void) {
+  struct timeval t;
+  size_t n = sizeof(t);
+  int mib[] = {1 /* CTL_KERN */, 21 /* KERN_BOOTTIME */};
+  if (sys_sysctl(mib, 2, &t, &n, 0, 0) == -1)
+    __builtin_trap();
+  return timeval_totimespec(t);
+}
+
 static void sys_clock_gettime_mono_init(void) {
-  g_mono.base_wall = timespec_real();
-  g_mono.base_tick = rdtsc();
+  g_mono.base = rdtsc();
+  if (IsXnu()) {
+    g_mono.boot = get_boot_time_xnu();
+  } else {
+    __builtin_trap();
+  }
 }
 
 int sys_clock_gettime_mono(struct timespec *time) {
   uint64_t nanos;
   uint64_t cycles;
-#ifdef __x86_64__
-  // intel architecture guarantees that a mapping exists between rdtsc &
-  // nanoseconds only if the cpu advertises invariant timestamps support
-  if (!X86_HAVE(INVTSC))
-    return -EINVAL;
-#endif
   cosmo_once(&g_mono.once, sys_clock_gettime_mono_init);
-  cycles = rdtsc() - g_mono.base_tick;
+  // ensure we get the full 64 bits of counting, which avoids wraparound
+  cycles = rdtsc() - g_mono.base;
   // this is a crude approximation, that's worked reasonably well so far
   // only the kernel knows the actual mapping between rdtsc and nanosecs
   // which we could attempt to measure ourselves using clock_gettime but
   // we'd need to impose 100 ms of startup latency for a guess this good
   nanos = cycles / 3;
-  *time = timespec_add(g_mono.base_wall, timespec_fromnanos(nanos));
+  *time = timespec_add(g_mono.boot, timespec_fromnanos(nanos));
   return 0;
 }

libc/calls/clock_gettime-nt.c

@@ -25,71 +25,90 @@
 #include "libc/nt/runtime.h"
 #include "libc/nt/synchronization.h"
 #include "libc/nt/thread.h"
+#include "libc/nt/time.h"
 
 #define _CLOCK_REALTIME           0
 #define _CLOCK_MONOTONIC          1
 #define _CLOCK_REALTIME_COARSE    2
 #define _CLOCK_BOOTTIME           3
 #define _CLOCK_PROCESS_CPUTIME_ID 4
 #define _CLOCK_THREAD_CPUTIME_ID  5
-
-static struct {
-  uint64_t base;
-  uint64_t freq;
-} g_winclock;
+#define _CLOCK_MONOTONIC_COARSE   6
 
 textwindows int sys_clock_gettime_nt(int clock, struct timespec *ts) {
-  uint64_t t;
+  uint64_t hectons;
   struct NtFileTime ft, ftExit, ftUser, ftKernel, ftCreation;
   switch (clock) {
     case _CLOCK_REALTIME:
-      if (ts) {
-        GetSystemTimePreciseAsFileTime(&ft);
-        *ts = FileTimeToTimeSpec(ft);
-      }
+      GetSystemTimePreciseAsFileTime(&ft);
+      *ts = FileTimeToTimeSpec(ft);
       return 0;
     case _CLOCK_REALTIME_COARSE:
-      if (ts) {
-        GetSystemTimeAsFileTime(&ft);
-        *ts = FileTimeToTimeSpec(ft);
-      }
+      GetSystemTimeAsFileTime(&ft);
+      *ts = FileTimeToTimeSpec(ft);
       return 0;
     case _CLOCK_MONOTONIC:
-      if (ts) {
-        QueryPerformanceCounter(&t);
-        t = ((t - g_winclock.base) * 1000000000) / g_winclock.freq;
-        *ts = timespec_fromnanos(t);
-      }
+      //
+      // "If you need a higher resolution timer, use the
+      //  QueryUnbiasedInterruptTime function, a multimedia timer, or a
+      //  high-resolution timer. The elapsed time retrieved by the
+      //  QueryUnbiasedInterruptTime function includes only time that
+      //  the system spends in the working state."
+      //
+      //                     —Quoth MSDN § Windows Time
+      //
+      QueryUnbiasedInterruptTimePrecise(&hectons);
+      *ts = timespec_fromnanos(hectons * 100);
+      return 0;
+    case _CLOCK_MONOTONIC_COARSE:
+      //
+      // "QueryUnbiasedInterruptTimePrecise is similar to the
+      //  QueryUnbiasedInterruptTime routine, but is more precise. The
+      //  interrupt time reported by QueryUnbiasedInterruptTime is based
+      //  on the latest tick of the system clock timer. The system clock
+      //  timer is the hardware timer that periodically generates
+      //  interrupts for the system clock. The uniform period between
+      //  system clock timer interrupts is referred to as a system clock
+      //  tick, and is typically in the range of 0.5 milliseconds to
+      //  15.625 milliseconds, depending on the hardware platform. The
+      //  interrupt time value retrieved by QueryUnbiasedInterruptTime
+      //  is accurate within a system clock tick. ¶To provide a system
+      //  time value that is more precise than that of
+      //  QueryUnbiasedInterruptTime, QueryUnbiasedInterruptTimePrecise
+      //  reads the timer hardware directly, therefore a
+      //  QueryUnbiasedInterruptTimePrecise call can be slower than a
+      //  QueryUnbiasedInterruptTime call."
+      //
+      //                     —Quoth MSDN § QueryUnbiasedInterruptTimePrecise
+      //
+      QueryUnbiasedInterruptTime(&hectons);
+      *ts = timespec_fromnanos(hectons * 100);
       return 0;
     case _CLOCK_BOOTTIME:
-      if (ts) {
-        *ts = timespec_frommillis(GetTickCount64());
-      }
+      //
+      // "Unbiased interrupt-time means that only time that the system
+      //  is in the working state is counted; therefore, the interrupt
+      //  time count is not "biased" by time the system spends in sleep
+      //  or hibernation."
+      //
+      //                     —Quoth MSDN § Interrupt Time
+      //
+      QueryInterruptTimePrecise(&hectons);
+      *ts = timespec_fromnanos(hectons * 100);
       return 0;
     case _CLOCK_PROCESS_CPUTIME_ID:
-      if (ts) {
-        GetProcessTimes(GetCurrentProcess(), &ftCreation, &ftExit, &ftKernel,
-                        &ftUser);
-        *ts = WindowsDurationToTimeSpec(ReadFileTime(ftUser) +
-                                        ReadFileTime(ftKernel));
-      }
+      GetProcessTimes(GetCurrentProcess(), &ftCreation, &ftExit, &ftKernel,
+                      &ftUser);
+      *ts = WindowsDurationToTimeSpec(ReadFileTime(ftUser) +
+                                      ReadFileTime(ftKernel));
       return 0;
     case _CLOCK_THREAD_CPUTIME_ID:
-      if (ts) {
-        GetThreadTimes(GetCurrentThread(), &ftCreation, &ftExit, &ftKernel,
-                       &ftUser);
-        *ts = WindowsDurationToTimeSpec(ReadFileTime(ftUser) +
-                                        ReadFileTime(ftKernel));
-      }
+      GetThreadTimes(GetCurrentThread(), &ftCreation, &ftExit, &ftKernel,
+                     &ftUser);
+      *ts = WindowsDurationToTimeSpec(ReadFileTime(ftUser) +
+                                      ReadFileTime(ftKernel));
       return 0;
     default:
       return -EINVAL;
   }
 }
-
-__attribute__((__constructor__(40))) static textstartup void winclock_init() {
-  if (IsWindows()) {
-    QueryPerformanceCounter(&g_winclock.base);
-    QueryPerformanceFrequency(&g_winclock.freq);
-  }
-}

libc/calls/clock_gettime-xnu.c

@@ -25,9 +25,6 @@
 #include "libc/sysv/consts/clock.h"
 #ifdef __x86_64__
 
-#define CTL_KERN      1
-#define KERN_BOOTTIME 21
-
 int sys_clock_gettime_xnu(int clock, struct timespec *ts) {
   long ax, dx;
   if (clock == CLOCK_REALTIME) {
@@ -47,31 +44,20 @@ int sys_clock_gettime_xnu(int clock, struct timespec *ts) {
     //   2. old xnu returns *ts in rax:rdx regs
     //
     // we assume this system call always succeeds
-    if (ts) {
-      asm volatile("syscall"
-                   : "=a"(ax), "=d"(dx)
-                   : "0"(0x2000000 | 116), "D"(ts), "S"(0), "1"(0)
-                   : "rcx", "r8", "r9", "r10", "r11", "memory");
-      if (ax) {
-        ts->tv_sec = ax;
-        ts->tv_nsec = dx;
-      }
-      ts->tv_nsec *= 1000;
+    asm volatile("syscall"
+                 : "=a"(ax), "=d"(dx)
+                 : "0"(0x2000000 | 116), "D"(ts), "S"(0), "1"(0)
+                 : "rcx", "r8", "r9", "r10", "r11", "memory");
+    if (ax) {
+      ts->tv_sec = ax;
+      ts->tv_nsec = dx;
     }
+    ts->tv_nsec *= 1000;
     return 0;
-  } else if (clock == CLOCK_MONOTONIC) {
-    if (!ts)
-      return 0;
+  } else if (clock == CLOCK_BOOTTIME ||   //
+             clock == CLOCK_MONOTONIC ||  //
+             clock == CLOCK_MONOTONIC_COARSE) {
     return sys_clock_gettime_mono(ts);
-  } else if (clock == CLOCK_BOOTTIME) {
-    struct timeval x;
-    size_t n = sizeof(x);
-    int mib[] = {CTL_KERN, KERN_BOOTTIME};
-    if (sysctl(mib, ARRAYLEN(mib), &x, &n, 0, 0) == -1)
-      return -1;
-    if (ts)
-      *ts = timeval_totimespec(timeval_sub(timeval_real(), x));
-    return 0;
   } else {
     return -EINVAL;
   }