tiny.game.settle

1pub const settle = @import("settle.zig");

1//! A detector that reports a change to a file once the file has held still for a window of time.2//!3//! A host that reloads code after a rebuild wants to act on each rebuild once, as soon as the new4//! file is complete. A compiler writes a library file over a stretch of time, and the file's size5//! can change more than once during one write, so a host that acts on the first change can load a6//! half-written file.7//!8//! At each look the caller hands the detector the file's modification time and size at that look (a9//! *stamp*) and the current time, so the detector reads no clock and no file of its own. A stamp10//! that differs from the last one starts a window at the current time, and a later look with the11//! same stamp at or past the window's end reports the change. A change seen while an earlier one12//! waits starts the window again. The detector reports each change a single time, and then waits13//! for the next change. The detector's first look records a baseline and reports nothing.14const std = @import("std");1516/// A file's modification time and size, taken at one look. A caller builds one from each look at17/// the file and passes it to `Settle.observe`.18pub const Stamp = struct {19    /// The file's modification time in nanoseconds, as the file system reports it.20    mtime_ns: i128,21    /// The file's size in bytes.22    size: u64,2324    /// Returns true when both the modification time and the size match. `Settle.observe` tells with25    /// it whether the file changed since the last look.26    pub fn eql(a: Stamp, b: Stamp) bool {27        return a.mtime_ns == b.mtime_ns and a.size == b.size;28    }29};3031/// The state of one change detector: the last stamp it saw and, while a change waits, the time at32/// which it may report that change. A reloader keeps one for the file it watches and hands it a33/// stamp at each poll. A detector starts empty, as `Settle{}`, and its first look records a34/// baseline.35pub const Settle = struct {36    seen: ?Stamp = null,37    fire_at: ?i128 = null,3839    /// Records one look at the file and returns true when a change has held still for `window_ns`40    /// since the look that saw it. A caller looks at the file on its own schedule and acts on the41    /// change when the call returns true. The first call records `stamp` as a baseline and returns42    /// false. A stamp that differs from the last one is recorded, starts the window at `now_ns`,43    /// and returns false. The same stamp returns false before the window's end and true at the44    /// first look at or past it. After a true result, the call returns false until the stamp45    /// changes again and a new window ends. The call reports only at a look, so a caller that looks46    /// less often than the window hears of the change at its next look.47    pub fn observe(self: *Settle, stamp: Stamp, now_ns: i128, window_ns: i128) bool {48        const seen = self.seen orelse {49            self.seen = stamp;50            return false;51        };52        if (!seen.eql(stamp)) {53            self.seen = stamp;54            self.fire_at = now_ns + window_ns;55            return false;56        }57        const deadline = self.fire_at orelse return false;58        if (now_ns < deadline) return false;59        self.fire_at = null;60        return true;61    }62};6364const window: i128 = 100;6566test "the first observation is a baseline that never fires" {67    var settle = Settle{};68    try std.testing.expect(!settle.observe(.{ .mtime_ns = 5, .size = 10 }, 0, window));69    try std.testing.expect(!settle.observe(.{ .mtime_ns = 5, .size = 10 }, 1_000, window));70}7172test "a settled change fires once after the window elapses" {73    var settle = Settle{};74    _ = settle.observe(.{ .mtime_ns = 5, .size = 10 }, 0, window);75    try std.testing.expect(!settle.observe(.{ .mtime_ns = 6, .size = 12 }, 10, window));76    try std.testing.expect(!settle.observe(.{ .mtime_ns = 6, .size = 12 }, 50, window));77    try std.testing.expect(settle.observe(.{ .mtime_ns = 6, .size = 12 }, 110, window));78    try std.testing.expect(!settle.observe(.{ .mtime_ns = 6, .size = 12 }, 200, window));79}8081test "an unsettled file keeps re-arming and does not fire mid-write" {82    var settle = Settle{};83    _ = settle.observe(.{ .mtime_ns = 5, .size = 10 }, 0, window);84    try std.testing.expect(!settle.observe(.{ .mtime_ns = 6, .size = 12 }, 10, window));85    try std.testing.expect(!settle.observe(.{ .mtime_ns = 6, .size = 40 }, 80, window));86    try std.testing.expect(!settle.observe(.{ .mtime_ns = 6, .size = 99 }, 130, window));87    try std.testing.expect(!settle.observe(.{ .mtime_ns = 6, .size = 99 }, 200, window));88    try std.testing.expect(settle.observe(.{ .mtime_ns = 6, .size = 99 }, 240, window));89}9091test "a second change after a fire arms again" {92    var settle = Settle{};93    _ = settle.observe(.{ .mtime_ns = 5, .size = 10 }, 0, window);94    _ = settle.observe(.{ .mtime_ns = 6, .size = 12 }, 10, window);95    try std.testing.expect(settle.observe(.{ .mtime_ns = 6, .size = 12 }, 120, window));96    try std.testing.expect(!settle.observe(.{ .mtime_ns = 7, .size = 14 }, 130, window));97    try std.testing.expect(settle.observe(.{ .mtime_ns = 7, .size = 14 }, 240, window));98}