time: introduce Instant (#10972)

lib/std/c/darwin.zig

@@ -64,7 +64,8 @@ pub const fstat = if (native_arch == .aarch64) private.fstat else private.@"fsta
 pub const fstatat = if (native_arch == .aarch64) private.fstatat else private.@"fstatat$INODE64";
 
 pub extern "c" fn mach_absolute_time() u64;
-pub extern "c" fn mach_timebase_info(tinfo: ?*mach_timebase_info_data) void;
+pub extern "c" fn mach_continuous_time() u64;
+pub extern "c" fn mach_timebase_info(tinfo: ?*mach_timebase_info_data) kern_return_t;
 
 pub extern "c" fn malloc_size(?*const anyopaque) usize;
 pub extern "c" fn posix_memalign(memptr: *?*anyopaque, alignment: usize, size: usize) c_int;

lib/std/time.zig

@@ -4,22 +4,23 @@ const assert = std.debug.assert;
 const testing = std.testing;
 const os = std.os;
 const math = std.math;
-const is_windows = builtin.os.tag == .windows;
 
 pub const epoch = @import("time/epoch.zig");
 
 /// Spurious wakeups are possible and no precision of timing is guaranteed.
 pub fn sleep(nanoseconds: u64) void {
     // TODO: opting out of async sleeping?
-    if (std.io.is_async)
+    if (std.io.is_async) {
         return std.event.Loop.instance.?.sleep(nanoseconds);
+    }
 
-    if (is_windows) {
+    if (builtin.os.tag == .windows) {
         const big_ms_from_ns = nanoseconds / ns_per_ms;
         const ms = math.cast(os.windows.DWORD, big_ms_from_ns) catch math.maxInt(os.windows.DWORD);
         os.windows.kernel32.Sleep(ms);
         return;
     }
+
     if (builtin.os.tag == .wasi) {
         const w = std.os.wasi;
         const userdata: w.userdata_t = 0x0123_45678;
@@ -50,6 +51,10 @@ pub fn sleep(nanoseconds: u64) void {
     std.os.nanosleep(s, ns);
 }
 
+test "sleep" {
+    sleep(1);
+}
+
 /// Get a calendar timestamp, in seconds, relative to UTC 1970-01-01.
 /// Precision of timing depends on the hardware and operating system.
 /// The return value is signed because it is possible to have a date that is
@@ -75,7 +80,7 @@ pub fn milliTimestamp() i64 {
 /// before the epoch.
 /// See `std.os.clock_gettime` for a POSIX timestamp.
 pub fn nanoTimestamp() i128 {
-    if (is_windows) {
+    if (builtin.os.tag == .windows) {
         // FileTime has a granularity of 100 nanoseconds and uses the NTFS/Windows epoch,
         // which is 1601-01-01.
         const epoch_adj = epoch.windows * (ns_per_s / 100);
@@ -84,12 +89,14 @@ pub fn nanoTimestamp() i128 {
         const ft64 = (@as(u64, ft.dwHighDateTime) << 32) | ft.dwLowDateTime;
         return @as(i128, @bitCast(i64, ft64) + epoch_adj) * 100;
     }
+
     if (builtin.os.tag == .wasi and !builtin.link_libc) {
         var ns: os.wasi.timestamp_t = undefined;
         const err = os.wasi.clock_time_get(os.wasi.CLOCK.REALTIME, 1, &ns);
         assert(err == .SUCCESS);
         return ns;
     }
+
     var ts: os.timespec = undefined;
     os.clock_gettime(os.CLOCK.REALTIME, &ts) catch |err| switch (err) {
         error.UnsupportedClock, error.Unexpected => return 0, // "Precision of timing depends on hardware and OS".
@@ -97,6 +104,18 @@ pub fn nanoTimestamp() i128 {
     return (@as(i128, ts.tv_sec) * ns_per_s) + ts.tv_nsec;
 }
 
+test "timestamp" {
+    const margin = ns_per_ms * 50;
+
+    const time_0 = milliTimestamp();
+    sleep(ns_per_ms);
+    const time_1 = milliTimestamp();
+    const interval = time_1 - time_0;
+    try testing.expect(interval > 0);
+    // Tests should not depend on timings: skip test if outside margin.
+    if (!(interval < margin)) return error.SkipZigTest;
+}
+
 // Divisions of a nanosecond.
 pub const ns_per_us = 1000;
 pub const ns_per_ms = 1000 * ns_per_us;
@@ -127,149 +146,162 @@ pub const s_per_hour = s_per_min * 60;
 pub const s_per_day = s_per_hour * 24;
 pub const s_per_week = s_per_day * 7;
 
-/// A monotonic high-performance timer.
+/// An Instant represents a timestamp with respect to the currently
-/// Timer.start() must be called to initialize the struct, which captures
+/// executing program that ticks during suspend and can be used to 
-/// the counter frequency on windows and darwin, records the resolution,
+/// record elapsed time unlike `nanoTimestamp`.
-/// and gives the user an opportunity to check for the existnece of
+///
-/// monotonic clocks without forcing them to check for error on each read.
+/// It tries to sample the system's fastest and most precise timer available.
-/// .resolution is in nanoseconds on all platforms but .start_time's meaning
+/// It also tries to be monotonic, but this is not a guarantee due to OS/hardware bugs.
-/// depends on the OS. On Windows and Darwin it is a hardware counter
+/// If you need monotonic readings for elapsed time, consider `Timer` instead.
-/// value that requires calculation to convert to a meaninful unit.
+pub const Instant = struct {
+    timestamp: if (is_posix) os.timespec else u64,
+
+    // true if we should use clock_gettime()
+    const is_posix = switch (builtin.os.tag) {
+        .wasi => builtin.link_libc,
+        .windows => false,
+        else => true,
+    };
+
+    /// Queries the system for the current moment of time as an Instant.
+    /// This is not guaranteed to be monotonic or steadily increasing, but for most implementations it is.
+    /// Returns `error.Unsupported` when a suitable clock is not detected.
+    pub fn now() error{Unsupported}!Instant {
+        // QPC on windows doesn't fail on >= XP/2000 and includes time suspended.
+        if (builtin.os.tag == .windows) {
+            return Instant{ .timestamp = os.windows.QueryPerformanceCounter() };
+        }
+
+        // On WASI without libc, use clock_time_get directly.
+        if (builtin.os.tag == .wasi and !builtin.link_libc) {
+            var ns: os.wasi.timestamp_t = undefined;
+            const rc = os.wasi.clock_time_get(os.wasi.CLOCK.MONOTONIC, 1, &ns);
+            if (rc != .SUCCESS) return error.Unsupported;
+            return Instant{ .timestamp = ns };
+        }
+
+        // On darwin, use UPTIME_RAW instead of MONOTONIC as it ticks while suspended.
+        // On linux, use BOOTTIME instead of MONOTONIC as it ticks while suspended.
+        // On freebsd derivatives, use MONOTONIC_FAST as currently there's no precision tradeoff.
+        // On other posix systems, MONOTONIC is generally the fastest and ticks while suspended.
+        const clock_id = switch (builtin.os.tag) {
+            .macos, .ios, .tvos, .watchos => os.CLOCK.UPTIME_RAW,
+            .freebsd, .dragonfly => os.CLOCK.MONOTONIC_FAST,
+            .linux => os.CLOCK.BOOTTIME,
+            else => os.CLOCK.MONOTONIC,
+        };
+
+        var ts: os.timespec = undefined;
+        os.clock_gettime(clock_id, &ts) catch return error.Unsupported;
+        return Instant{ .timestamp = ts };
+    }
+
+    /// Quickly compares two instances between each other.
+    pub fn order(self: Instant, other: Instant) std.math.Order {
+        // windows and wasi timestamps are in u64 which is easily comparible
+        if (!is_posix) {
+            return std.math.order(self.timestamp, other.timestamp);
+        }
+
+        var ord = std.math.order(self.timestamp.tv_sec, other.timestamp.tv_sec);
+        if (ord == .eq) {
+            ord = std.math.order(self.timestamp.tv_nsec, other.timestamp.tv_nsec);
+        }
+        return ord;
+    }
+
+    /// Returns elapsed time in nanoseconds since the `earlier` Instant.
+    /// This assumes that the `earlier` Instant represents a moment in time before or equal to `self`.
+    /// This also assumes that the time that has passed between both Instants fits inside a u64 (~585 yrs).
+    pub fn since(self: Instant, earlier: Instant) u64 {
+        if (builtin.os.tag == .windows) {
+            // We don't need to cache QPF as it's internally just a memory read to KUSER_SHARED_DATA
+            // (a read-only page of info updated and mapped by the kernel to all processes):
+            // https://docs.microsoft.com/en-us/windows-hardware/drivers/ddi/ntddk/ns-ntddk-kuser_shared_data
+            // https://www.geoffchappell.com/studies/windows/km/ntoskrnl/inc/api/ntexapi_x/kuser_shared_data/index.htm
+            const qpc = self.timestamp - earlier.timestamp;
+            const qpf = os.windows.QueryPerformanceFrequency();
+
+            // 10Mhz (1 qpc tick every 100ns) is a common enough QPF value that we can optimize on it.
+            // https://github.com/microsoft/STL/blob/785143a0c73f030238ef618890fd4d6ae2b3a3a0/stl/inc/chrono#L694-L701
+            const common_qpf = 10_000_000;
+            if (qpf == common_qpf) {
+                return qpc * (ns_per_s / common_qpf);
+            }
+
+            // Convert to ns using fixed point.
+            const scale = @as(u64, std.time.ns_per_s << 32) / @intCast(u32, qpf);
+            const result = (@as(u96, qpc) * scale) >> 32;
+            return @truncate(u64, result);
+        }
+
+        // WASI timestamps are directly in nanoseconds
+        if (builtin.os.tag == .wasi and !builtin.link_libc) {
+            return self.timestamp - earlier.timestamp;
+        }
+
+        // Convert timespec diff to ns
+        const seconds = @intCast(u64, self.timestamp.tv_sec - earlier.timestamp.tv_sec);
+        const elapsed = (seconds * ns_per_s) + @intCast(u32, self.timestamp.tv_nsec);
+        return elapsed - @intCast(u32, earlier.timestamp.tv_nsec);
+    }
+};
+
+/// A monotonic, high performance timer.
+///
+/// Timer.start() is used to initalize the timer
+/// and gives the caller an opportunity to check for the existence of a supported clock.
+/// Once a supported clock is discovered,
+/// it is assumed that it will be available for the duration of the Timer's use.
+///
+/// Monotonicity is ensured by saturating on the most previous sample.
+/// This means that while timings reported are monotonic,
+/// they're not guaranteed to tick at a steady rate as this is up to the underlying system.  
 pub const Timer = struct {
-    ///if we used resolution's value when performing the
+    started: Instant,
-    ///  performance counter calc on windows/darwin, it would
+    previous: Instant,
-    ///  be less precise
-    frequency: switch (builtin.os.tag) {
-        .windows => u64,
-        .macos, .ios, .tvos, .watchos => os.darwin.mach_timebase_info_data,
-        else => void,
-    },
-    resolution: u64,
-    start_time: u64,
 
     pub const Error = error{TimerUnsupported};
 
-    /// At some point we may change our minds on RAW, but for now we're
+    /// Initialize the timer by querying for a supported clock.
-    /// sticking with posix standard MONOTONIC. For more information, see:
+    /// Returns `error.TimerUnsupported` when such a clock is unavailable.
-    /// https://github.com/ziglang/zig/pull/933
+    /// This should only fail in hostile environments such as linux seccomp misuse.
-    const monotonic_clock_id = os.CLOCK.MONOTONIC;
-
-    /// Initialize the timer structure.
-    /// Can only fail when running in a hostile environment that intentionally injects
-    /// error values into syscalls, such as using seccomp on Linux to intercept
-    /// `clock_gettime`.
     pub fn start() Error!Timer {
-        // This gives us an opportunity to grab the counter frequency in windows.
+        const current = Instant.now() catch return error.TimerUnsupported;
-        // On Windows: QueryPerformanceCounter will succeed on anything >= XP/2000.
+        return Timer{ .started = current, .previous = current };
-        // On Posix: CLOCK.MONOTONIC will only fail if the monotonic counter is not
-        // supported, or if the timespec pointer is out of bounds, which should be
-        // impossible here barring cosmic rays or other such occurrences of
-        // incredibly bad luck.
-        // On Darwin: This cannot fail, as far as I am able to tell.
-        if (is_windows) {
-            const freq = os.windows.QueryPerformanceFrequency();
-            return Timer{
-                .frequency = freq,
-                .resolution = @divFloor(ns_per_s, freq),
-                .start_time = os.windows.QueryPerformanceCounter(),
-            };
-        } else if (comptime builtin.target.isDarwin()) {
-            var freq: os.darwin.mach_timebase_info_data = undefined;
-            os.darwin.mach_timebase_info(&freq);
-
-            return Timer{
-                .frequency = freq,
-                .resolution = @divFloor(freq.numer, freq.denom),
-                .start_time = os.darwin.mach_absolute_time(),
-            };
-        } else {
-            // On Linux, seccomp can do arbitrary things to our ability to call
-            // syscalls, including return any errno value it wants and
-            // inconsistently throwing errors. Since we can't account for
-            // abuses of seccomp in a reasonable way, we'll assume that if
-            // seccomp is going to block us it will at least do so consistently
-            var res: os.timespec = undefined;
-            os.clock_getres(monotonic_clock_id, &res) catch return error.TimerUnsupported;
-
-            var ts: os.timespec = undefined;
-            os.clock_gettime(monotonic_clock_id, &ts) catch return error.TimerUnsupported;
-
-            return Timer{
-                .resolution = @intCast(u64, res.tv_sec) * ns_per_s + @intCast(u64, res.tv_nsec),
-                .start_time = @intCast(u64, ts.tv_sec) * ns_per_s + @intCast(u64, ts.tv_nsec),
-                .frequency = {},
-            };
-        }
     }
 
-    /// Reads the timer value since start or the last reset in nanoseconds
+    /// Reads the timer value since start or the last reset in nanoseconds.
-    pub fn read(self: Timer) u64 {
+    pub fn read(self: *Timer) u64 {
-        var clock = clockNative() - self.start_time;
+        const current = self.sample();
-        return self.nativeDurationToNanos(clock);
+        return current.since(self.started);
     }
 
     /// Resets the timer value to 0/now.
     pub fn reset(self: *Timer) void {
-        self.start_time = clockNative();
+        const current = self.sample();
+        self.started = current;
     }
 
-    /// Returns the current value of the timer in nanoseconds, then resets it
+    /// Returns the current value of the timer in nanoseconds, then resets it.
     pub fn lap(self: *Timer) u64 {
-        var now = clockNative();
+        const current = self.sample();
-        var lap_time = self.nativeDurationToNanos(now - self.start_time);
+        defer self.started = current;
-        self.start_time = now;
+        return current.since(self.started);
-        return lap_time;
     }
 
-    fn clockNative() u64 {
+    /// Returns an Instant sampled at the callsite that is 
-        if (is_windows) {
+    /// guaranteed to be monotonic with respect to the timer's starting point.
-            return os.windows.QueryPerformanceCounter();
+    fn sample(self: *Timer) Instant {
+        const current = Instant.now() catch unreachable;
+        if (current.order(self.previous) == .gt) {
+            self.previous = current;
         }
-        if (comptime builtin.target.isDarwin()) {
+        return self.previous;
-            return os.darwin.mach_absolute_time();
-        }
-        var ts: os.timespec = undefined;
-        os.clock_gettime(monotonic_clock_id, &ts) catch unreachable;
-        return @intCast(u64, ts.tv_sec) * @as(u64, ns_per_s) + @intCast(u64, ts.tv_nsec);
-    }
-
-    fn nativeDurationToNanos(self: Timer, duration: u64) u64 {
-        if (is_windows) {
-            return safeMulDiv(duration, ns_per_s, self.frequency);
-        }
-        if (comptime builtin.target.isDarwin()) {
-            return safeMulDiv(duration, self.frequency.numer, self.frequency.denom);
-        }
-        return duration;
     }
 };
 
-// Calculate (a * b) / c without risk of overflowing too early because of the
+test "Timer + Instant" {
-// multiplication.
-fn safeMulDiv(a: u64, b: u64, c: u64) u64 {
-    const q = a / c;
-    const r = a % c;
-    // (a * b) / c == (a / c) * b + ((a % c) * b) / c
-    return (q * b) + (r * b) / c;
-}
-
-test "sleep" {
-    sleep(1);
-}
-
-test "timestamp" {
-    const margin = ns_per_ms * 50;
-
-    const time_0 = milliTimestamp();
-    sleep(ns_per_ms);
-    const time_1 = milliTimestamp();
-    const interval = time_1 - time_0;
-    try testing.expect(interval > 0);
-    // Tests should not depend on timings: skip test if outside margin.
-    if (!(interval < margin)) return error.SkipZigTest;
-}
-
-test "Timer" {
     const margin = ns_per_ms * 150;
 
     var timer = try Timer.start();