tiny.trace.Session

1pub const Session = struct {2    allocator: Allocator,3    mode: event.Mode,4    sink: ?event.Sink = null,5    source: ?event.Source = null,6    epoch: u64 = 0,7    next_seq: u64 = 1,8    sequence_exhausted: bool = false,9    replay_cursor: u64 = 0,10    last_checkpoint: ?event.Event = null,1112    pub fn initOff(allocator: Allocator) Session {13        return .{ .allocator = allocator, .mode = .off };14    }1516    pub fn initRecord(allocator: Allocator, sink: event.Sink) Session {17        return .{ .allocator = allocator, .mode = .record, .sink = sink };18    }1920    pub fn initReplay(allocator: Allocator, source: event.Source) Session {21        return .{ .allocator = allocator, .mode = .replay, .source = source };22    }2324    pub fn deinit(self: *Session) void {25        if (self.last_checkpoint) |*item| item.deinit(self.allocator);26        self.* = undefined;27    }2829    pub fn replayProgress(self: *const Session) ReplayProgress {30        const event_count = if (self.source) |source| source.count() else 0;31        std.debug.assert(self.replay_cursor <= event_count);32        return .{33            .cursor = self.replay_cursor,34            .event_count = event_count,35            .remaining_count = event_count - self.replay_cursor,36        };37    }3839    pub fn sessionStart(40        self: *Session,41        thread_id: event.ThreadId,42        label: []const u8,43    ) !event.Timepoint {44        const timepoint = try self.prepareTimepoint(thread_id);45        return try self.handleEvent(event.Event.sessionStart(timepoint, label));46    }4748    pub fn sessionEnd(49        self: *Session,50        thread_id: event.ThreadId,51        status: i64,52    ) !event.Timepoint {53        const timepoint = try self.prepareTimepoint(thread_id);54        return try self.handleEvent(event.Event.sessionEnd(timepoint, status));55    }5657    pub fn functionEnter(58        self: *Session,59        thread_id: event.ThreadId,60        site: event.Safepoint,61    ) !event.Timepoint {62        const timepoint = try self.prepareTimepoint(thread_id);63        return try self.handleEvent(event.Event.functionEnter(timepoint, site));64    }6566    pub fn functionExit(67        self: *Session,68        thread_id: event.ThreadId,69        site: event.Safepoint,70    ) !event.Timepoint {71        const timepoint = try self.prepareTimepoint(thread_id);72        return try self.handleEvent(event.Event.functionExit(timepoint, site));73    }7475    pub fn safepoint(76        self: *Session,77        thread_id: event.ThreadId,78        site: event.Safepoint,79    ) !event.Timepoint {80        const timepoint = try self.prepareTimepoint(thread_id);81        return try self.handleEvent(event.Event.safepointReached(timepoint, site));82    }8384    pub fn allocation(85        self: *Session,86        thread_id: event.ThreadId,87        object_id: u64,88        size: u64,89        alignment: u32,90        label: ?[]const u8,91    ) !event.Timepoint {92        const timepoint = try self.prepareTimepoint(thread_id);93        return try self.handleEvent(event.Event.allocation(94            timepoint,95            object_id,96            size,97            alignment,98            label,99        ));100    }101102    pub fn free(103        self: *Session,104        thread_id: event.ThreadId,105        object_id: u64,106    ) !event.Timepoint {107        const timepoint = try self.prepareTimepoint(thread_id);108        return try self.handleEvent(event.Event.free(timepoint, object_id));109    }110111    pub fn boundaryBytesAlloc(112        self: *Session,113        thread_id: event.ThreadId,114        operation: []const u8,115        recorded_value: ?[]const u8,116    ) ![]u8 {117        const timepoint = try self.prepareTimepoint(thread_id);118        switch (self.mode) {119            .off => {120                const source_value = recorded_value orelse return error.MissingBoundaryValue;121                const value = try self.allocator.dupe(u8, source_value);122                self.commitTimepoint(timepoint);123                return value;124            },125            .record => {126                const value = recorded_value orelse return error.MissingBoundaryValue;127                const owned = try self.allocator.dupe(u8, value);128                errdefer self.allocator.free(owned);129                try self.sink.?.append(event.Event.boundaryBytes(timepoint, operation, value));130                self.commitTimepoint(timepoint);131                return owned;132            },133            .replay => {134                const source = self.source.?;135                const actual = (try source.peek()) orelse return error.MissingReplayEvent;136                const recorded = actual.data orelse return error.ReplayEventMismatch;137                const expected = event.Event.boundaryBytes(timepoint, operation, recorded);138                if (!expected.eqlForReplay(actual.*)) return error.ReplayEventMismatch;139                const next_replay_cursor = try self.prepareReplayCursor();140                const value = try self.allocator.dupe(u8, recorded);141                source.advance();142                self.replay_cursor = next_replay_cursor;143                self.commitTimepoint(timepoint);144                return value;145            },146        }147    }148149    pub fn checkpointCapture(150        self: *Session,151        thread_id: event.ThreadId,152        label: []const u8,153        provider: checkpoint.Provider,154    ) !event.Timepoint {155        const timepoint = try self.prepareTimepoint(thread_id);156        const bytes = try provider.captureAlloc(self.allocator);157        defer self.allocator.free(bytes);158        return try self.handleEvent(event.Event.checkpoint(timepoint, label, bytes));159    }160161    pub fn checkpointRestore(162        self: *Session,163        thread_id: event.ThreadId,164        label: []const u8,165        provider: checkpoint.Provider,166    ) !event.Timepoint {167        const checkpoint_event = self.last_checkpoint orelse return error.MissingCheckpoint;168        const checkpoint_bytes = checkpoint_event.data orelse return error.MissingCheckpoint;169        const timepoint = try self.prepareTimepoint(thread_id);170        const expected = event.Event.checkpointRestore(timepoint, label);171        const prepared_replay = if (self.mode == .replay)172            try self.prepareReplay(expected)173        else174            null;175        const replay_timepoint = if (prepared_replay) |prepared|176            prepared.actual.timepoint177        else178            timepoint;179180        provider.prepareRestoreBytes(checkpoint_bytes) catch |err| {181            provider.cancelRestore();182            return err;183        };184        errdefer provider.cancelRestore();185186        if (self.mode == .record) try self.sink.?.append(expected);187188        provider.commitRestore();189        if (prepared_replay) |prepared| self.commitReplay(prepared);190        self.commitTimepoint(timepoint);191        return replay_timepoint;192    }193194    pub fn userEvent(195        self: *Session,196        thread_id: event.ThreadId,197        label: []const u8,198        bytes: []const u8,199    ) !event.Timepoint {200        const timepoint = try self.prepareTimepoint(thread_id);201        return try self.handleEvent(event.Event.user(timepoint, label, bytes));202    }203204    pub fn verifyReplayComplete(self: *Session) !void {205        if (self.mode != .replay) return;206        const source = self.source.?;207        if (self.replay_cursor != source.count()) return error.ReplayNotComplete;208        if (try source.peek() != null) return error.ReplayNotComplete;209    }210211    fn prepareTimepoint(self: *const Session, thread_id: event.ThreadId) !event.Timepoint {212        if (self.sequence_exhausted) return error.SequenceExhausted;213        return event.Timepoint{214            .epoch = self.epoch,215            .thread_id = thread_id,216            .seq = self.next_seq,217        };218    }219220    fn commitTimepoint(self: *Session, timepoint: event.Timepoint) void {221        std.debug.assert(!self.sequence_exhausted);222        std.debug.assert(timepoint.epoch == self.epoch);223        std.debug.assert(timepoint.seq == self.next_seq);224        if (self.next_seq == std.math.maxInt(u64)) {225            self.sequence_exhausted = true;226        } else {227            self.next_seq += 1;228        }229    }230231    fn handleEvent(self: *Session, expected: event.Event) !event.Timepoint {232        var owned_checkpoint: ?event.Event = null;233        errdefer if (owned_checkpoint) |*owned| owned.deinit(self.allocator);234235        var replay_timepoint: ?event.Timepoint = null;236        switch (self.mode) {237            .off => {238                if (expected.kind == .checkpoint) {239                    owned_checkpoint = try expected.cloneAlloc(self.allocator);240                }241            },242            .record => {243                if (expected.kind == .checkpoint) {244                    owned_checkpoint = try expected.cloneAlloc(self.allocator);245                }246                try self.sink.?.append(expected);247            },248            .replay => {249                const prepared = try self.prepareReplay(expected);250                replay_timepoint = prepared.actual.timepoint;251                if (prepared.actual.kind == .checkpoint) {252                    owned_checkpoint = try prepared.actual.cloneAlloc(self.allocator);253                }254                self.commitReplay(prepared);255            },256        }257258        self.commitTimepoint(expected.timepoint);259        if (owned_checkpoint) |owned| {260            self.replaceCheckpoint(owned);261            owned_checkpoint = null;262        }263        return replay_timepoint orelse expected.timepoint;264    }265266    const PreparedReplay = struct {267        source: event.Source,268        actual: *const event.Event,269        next_cursor: u64,270    };271272    fn prepareReplay(self: *Session, expected: event.Event) !PreparedReplay {273        const source = self.source.?;274        const actual = (try source.peek()) orelse return error.MissingReplayEvent;275        if (!expected.eqlForReplay(actual.*)) return error.ReplayEventMismatch;276        return .{277            .source = source,278            .actual = actual,279            .next_cursor = try self.prepareReplayCursor(),280        };281    }282283    fn prepareReplayCursor(self: *const Session) !u64 {284        return std.math.add(u64, self.replay_cursor, 1) catch285            return error.ReplayCursorExhausted;286    }287288    fn commitReplay(self: *Session, prepared: PreparedReplay) void {289        prepared.source.advance();290        self.replay_cursor = prepared.next_cursor;291    }292293    fn replaceCheckpoint(self: *Session, owned: event.Event) void {294        if (self.last_checkpoint) |*previous| previous.deinit(self.allocator);295        self.last_checkpoint = owned;296    }297};

1pub const Session = session.Session;