lib/trace/src/root.zig

daab053ee43316e1809a84551d573ddd1e5bf3d2

 1 //! The package records a run as a stream of events and replays that stream back
 2 //! into the program. A caller debugging a run that will not reproduce wants the
 3 //! run itself back, step for step, from a file. The recorder and replayer of
 4 //! events, running in one of three modes, off, record, or replay, is the
 5 //! *session*. Recording appends each event to the session's sink, and replaying
 6 //! compares each call against the next recorded event and fails when the two
 7 //! differ.
 8 //!
 9 //! One recorded step of a run, carrying its kind, its timepoint, and the
10 //! payload of that kind, is an *event*. The events cover session start and end,
11 //! function entry and exit, safepoints, allocations and frees, bytes crossing a
12 //! boundary, checkpoints, and a caller's own payloads. The function and site
13 //! identifiers naming where in the program an event was taken are a
14 //! *safepoint*. The thread, the epoch, and the sequence number that place an
15 //! event in the recorded order are its *timepoint*. Every event carries a
16 //! timepoint, so the recorded order survives the file. Replay follows the
17 //! recorded stream alone, which leaves an input the program reads from its
18 //! environment and the interleaving of its threads outside what a replay
19 //! reproduces. A failed call leaves the sequence, the replay cursor, and the
20 //! retained checkpoint as they were, so the same call can be retried.
21 //!
22 //! A caller's hook set for copying its state out and staging, committing, or
23 //! cancelling a restore of it is a *checkpoint provider*. A checkpoint provider
24 //! copies a caller's state into a checkpoint event, and stages a restore that
25 //! the session then commits or cancels. The header of a trace file, recording
26 //! the build identity, the counts of events, bytes, chunks, and blocks, and the
27 //! checksum over the events, is the *manifest*. The file opens with this
28 //! manifest. The reader works inside buffers sized before the read, and the
29 //! counts and the checksum are checked once the stream ends, so a truncated or
30 //! altered file ends in an error.
31 
32 pub const event = @import("event.zig");
33 pub const session = @import("session.zig");
34 pub const checkpoint = @import("checkpoint.zig");
35 pub const store = @import("store/root.zig");
36 pub const replay = @import("replay.zig");
37 
38 pub const Mode = event.Mode;
39 pub const ThreadId = event.ThreadId;
40 pub const Timepoint = event.Timepoint;
41 pub const Safepoint = event.Safepoint;
42 pub const EventKind = event.EventKind;
43 pub const Event = event.Event;
44 pub const EventSink = event.Sink;
45 pub const EventSource = event.Source;
46 pub const Frame = replay.Frame;
47 pub const SummaryEntry = replay.SummaryEntry;
48 pub const TimepointEntry = replay.TimepointEntry;
49 pub const ThreadEntry = replay.ThreadEntry;
50 pub const ObjectEntry = replay.ObjectEntry;
51 
52 pub const Session = session.Session;
53 pub const ReplayProgress = session.ReplayProgress;
54 pub const CheckpointProvider = checkpoint.Provider;
55 pub const Manifest = store.Manifest;
56 pub const TraceLimits = store.Limits;
57 pub const TraceReader = store.Reader;
58 pub const TraceReaderLimits = store.ReaderLimits;
59 pub const TraceReaderCapacity = store.ReaderCapacity;
60 pub const TraceReaderCapacityError = store.ReaderCapacityError;
61 pub const TraceReaderStorage = store.ReaderStorage;
62 pub const TraceReaderStorageStatus = store.ReaderStorageStatus;
63 pub const TraceReaderStorageExhaustion = store.ReaderStorageExhaustion;
64 pub const TraceWriter = store.Writer;
65 pub const TraceWriterLimits = store.WriterLimits;
66 pub const TraceWriterCapacity = store.WriterCapacity;
67 pub const TraceWriterCapacityError = store.WriterCapacityError;
68 pub const TraceWriterStorage = store.WriterStorage;
69 pub const TraceWriterStorageStatus = store.WriterStorageStatus;
70 pub const TraceWriterStorageExhaustion = store.WriterStorageExhaustion;
71 pub const VerifyResult = store.VerifyResult;