//! Wall-clock frame history, independent of the sketch's replay clock. const Timing = @This(); const std = @import("std"); pub const capacity = 240; pub const frames_per_column = 8; pub const Metric = enum { frame, work }; pub const Sample = struct { frame: u64 = 0, work: u64 = 0 }; pub const Stats = struct { mean: f64 = 0, p90: f64 = 0, p99: f64 = 0, max: f64 = 0, }; visible: bool = false, metric: Metric = .frame, samples: [capacity]Sample = @splat(.{}), count: usize = 0, next: usize = 0, dirty: bool = true, cached: [2]Stats = @splat(.{}), labels: [4][96]u8 = undefined, label_lengths: [4]usize = @splat(0), label_elapsed: u64 = 0, ceiling: f64 = 1.25, graph: [capacity]Sample = @splat(.{}), graph_count: usize = 0, graph_next: usize = 0, group_count: usize = 0, group_peak: Sample = .{}, pub fn add(self: *Timing, sample: Sample) void { self.samples[self.next] = sample; self.next = (self.next + 1) % capacity; self.count = @min(self.count + 1, capacity); self.label_elapsed +|= sample.frame; // Refresh text at most four times a second; collection never allocates or sorts. if (self.label_elapsed >= 250 * std.time.ns_per_ms) { self.dirty = true; self.label_elapsed = 0; } self.group_peak.frame = @max(self.group_peak.frame, sample.frame); self.group_peak.work = @max(self.group_peak.work, sample.work); self.group_count += 1; if (self.group_count == frames_per_column) { self.graph[self.graph_next] = self.group_peak; self.graph_next = (self.graph_next + 1) % capacity; self.graph_count = @min(self.graph_count + 1, capacity); self.group_count = 0; self.group_peak = .{}; } } pub fn graphAt(self: *const Timing, index: usize) Sample { std.debug.assert(index < self.graph_count); return self.graph[(self.graph_next + capacity - self.graph_count + index) % capacity]; } pub fn label(self: *const Timing, index: usize) []const u8 { return self.labels[index][0..self.label_lengths[index]]; } pub fn setLabel(self: *Timing, index: usize, comptime fmt: []const u8, args: anytype) void { const text = std.mem.print(&self.labels[index], fmt, args) catch unreachable; self.label_lengths[index] = text.len; } pub fn sampleAt(self: *const Timing, index: usize) Sample { std.debug.assert(index < self.count); return self.samples[(self.next + capacity - self.count + index) % capacity]; } pub fn value(sample: Sample, metric: Metric) u64 { return switch (metric) { .frame => sample.frame, .work => sample.work, }; } pub fn ms(ns: u64) f64 { return @as(f64, @floatFromInt(ns)) / std.time.ns_per_ms; } pub fn stats(self: *const Timing, metric: Metric) Stats { if (self.count == 0) return .{}; var sorted: [capacity]u64 = undefined; var total: f64 = 0; for (sorted[0..self.count], 0..) |*v, i| { v.* = value(self.sampleAt(i), metric); total += ms(v.*); } const values = sorted[0..self.count]; std.mem.sort(u64, values, {}, std.sort.asc(u64)); return .{ .mean = total / @as(f64, @floatFromInt(values.len)), .p90 = ms(values[(values.len * 90 + 99) / 100 - 1]), .p99 = ms(values[(values.len * 99 + 99) / 100 - 1]), .max = ms(values[values.len - 1]), }; } pub fn command(self: *Timing, arg: ?[]const u8) !void { if (arg) |name| { if (std.mem.eql(u8, name, "on")) { self.visible = true; } else if (std.mem.eql(u8, name, "off")) { self.visible = false; } else if (std.mem.eql(u8, name, "reset")) { self.* = .{ .visible = self.visible, .metric = self.metric }; } else if (std.meta.stringToEnum(Metric, name)) |metric| { self.metric = metric; self.visible = true; } else return error.ExpectedTimingOnOffFrameWorkResetStats; } else self.visible = !self.visible; self.dirty = true; } test "timing history percentiles, wrap, reset and commands" { var t: Timing = .{}; try std.testing.expectEqual(@as(f64, 0), t.stats(.frame).p99); t.add(.{ .frame = 1000000, .work = 500000 }); try std.testing.expectEqual(@as(f64, 0.5), t.stats(.work).p90); try t.command("reset"); for (1..401) |i| t.add(.{ .frame = i * 1000000, .work = i * 1000 }); try std.testing.expectEqual(capacity, t.count); try std.testing.expectEqual(@as(u64, 161000000), t.sampleAt(0).frame); const s = t.stats(.frame); try std.testing.expectEqual(@as(f64, 280.5), s.mean); try std.testing.expectEqual(@as(f64, 376), s.p90); try std.testing.expectEqual(@as(f64, 398), s.p99); try std.testing.expectEqual(@as(f64, 400), s.max); try t.command("work"); try t.command("reset"); try std.testing.expect(t.visible and t.metric == .work and t.count == 0); try t.command(null); try std.testing.expect(!t.visible); try t.command("on"); try std.testing.expect(t.visible); try t.command("off"); try std.testing.expect(!t.visible); try std.testing.expectError(error.ExpectedTimingOnOffFrameWorkResetStats, t.command("bogus")); } test "timing graph keeps peaks while scrolling eight times slower" { var t: Timing = .{}; for (0..7) |_| t.add(.{ .frame = 10, .work = 1 }); try std.testing.expectEqual(@as(usize, 0), t.graph_count); t.add(.{ .frame = 100, .work = 5 }); try std.testing.expectEqual(@as(usize, 1), t.graph_count); try std.testing.expectEqual(Sample{ .frame = 100, .work = 5 }, t.graphAt(0)); for (0..capacity * frames_per_column) |_| t.add(.{ .frame = 20, .work = 2 }); try std.testing.expectEqual(capacity, t.graph_count); try std.testing.expectEqual(Sample{ .frame = 20, .work = 2 }, t.graphAt(0)); try t.command("reset"); try std.testing.expectEqual(@as(usize, 0), t.graph_count); try std.testing.expectEqual(@as(usize, 0), t.group_count); } test "timing readouts refresh quarterly and use fixed text storage" { var t: Timing = .{}; t.dirty = false; for (0..24) |_| t.add(.{ .frame = 10 * std.time.ns_per_ms }); try std.testing.expect(!t.dirty); t.add(.{ .frame = 10 * std.time.ns_per_ms }); try std.testing.expect(t.dirty); t.setLabel(0, "p99 {d:.3}", .{@as(f64, 0.123)}); try std.testing.expectEqualStrings("p99 0.123", t.label(0)); }