lib/coz/src/root.zig

daab053ee43316e1809a84551d573ddd1e5bf3d2

 1 //! A caller with a profile full of hot lines still has to guess which line is
 2 //! worth optimizing. The package answers that question by measuring what a
 3 //! speedup of one code region would do to the whole program's rate of progress,
 4 //! called *causal profiling*.
 5 //!
 6 //! A program marks where its useful work completes using either one counter or
 7 //! a pair of counters. Bumping a named counter records a *progress point*. A
 8 //! named pair of begin and end counters whose difference gives the work in
 9 //! flight between them forms a *latency scope*.
10 //!
11 //! To test a line, the runtime conducts one run of a drawn speedup for a fixed
12 //! duration, called an *experiment*. The runtime samples which line each thread
13 //! is running through the performance counters and matches each sample against
14 //! the line the current experiment selected. The experiment draws a speedup for
15 //! that selected line, from zero to the whole sample period. The runtime
16 //! applies this speedup by holding the rest of the program back. The
17 //! nanoseconds a thread is held back so that the selected line runs relatively
18 //! faster form the *delay*. A thread whose sample lands on the selected line is
19 //! credited with that delay, and every other thread waits until it has caught
20 //! up to the global delay. The runtime measures the gap between the credited
21 //! line and the delayed remainder. The fraction of the sample period the
22 //! selected line is credited with, from zero to one, is the *virtual speedup*
23 //! the experiment reports. Each experiment runs for a duration that doubles or
24 //! halves toward a target number of progress-point deltas, followed by a
25 //! cool-off period.
26 //!
27 //! The runtime writes the run as a stream of JSON lines carrying startup,
28 //! experiment, throughput, latency, and sampling records. Analysis reads that
29 //! stream and reports, for each selected line and progress point, the program
30 //! speedup measured at each virtual speedup, the slope through those points,
31 //! and a support status saying how much of the curve the run covered.
32 //!
33 //! The marker calls do nothing while no runtime is installed, so a program can
34 //! keep them in place for builds that run without the profiler.
35 
36 pub const analysis = @import("analysis.zig");
37 pub const abi = @import("abi.zig");
38 pub const debug_info = @import("debug.zig");
39 pub const delay = @import("delay.zig");
40 pub const experiment = @import("experiment.zig");
41 pub const loaded_files = @import("files.zig");
42 pub const path_filter = @import("filter.zig");
43 pub const profile = @import("profile.zig");
44 pub const profile_file = @import("file.zig");
45 pub const profiler = @import("profiler.zig");
46 pub const progress_point = @import("point.zig");
47 pub const registry = @import("registry.zig");
48 pub const sampler = @import("sampler.zig");
49 pub const signals = @import("signals.zig");
50 pub const source_map = @import("map.zig");
51 pub const thread = @import("thread.zig");
52 
53 const runtime = @import("runtime.zig");
54 
55 pub const CounterKind = abi.CounterKind;
56 pub const Counter = abi.Counter;
57 pub const ExperimentRunOptions = profiler.ExperimentRunOptions;
58 pub const ExperimentStepOptions = profiler.ExperimentStepOptions;
59 pub const ExperimentStepResult = profiler.ExperimentStepResult;
60 pub const Profiler = profiler.Profiler;
61 pub const ProfileFile = profile_file.Writer;
62 pub const Registry = registry.Registry;
63 pub const Sampler = sampler.Sampler;
64 pub const Thread = thread.Thread;
65 
66 pub const RuntimeOptions = runtime.RuntimeOptions;
67 pub const Runtime = runtime.Runtime;
68 
69 pub const runtimeUnavailable = runtime.runtimeUnavailable;
70 pub const profilerPresent = runtime.profilerPresent;
71 pub const installSamplingHandler = runtime.installSamplingHandler;
72 pub const installProfiler = runtime.installProfiler;
73 pub const uninstallProfiler = runtime.uninstallProfiler;
74 pub const progress = runtime.progress;
75 pub const progressNamed = runtime.progressNamed;
76 pub const begin = runtime.begin;
77 pub const end = runtime.end;
78 pub const Scope = runtime.Scope;
79 pub const scope = runtime.scope;
80 pub const preBlock = runtime.preBlock;
81 pub const catchUp = runtime.catchUp;
82 pub const postBlock = runtime.postBlock;