Esc

Iprof_Trace

moduleextensionexperimentalSource
  • macOS: Everything works on macOS
  • Linux: Everything works on Linux
  • Windows: Everything works on Windows
  • Wasm: Everything works on Wasm
·since 0.36.1

#import "Extensions/Iprof_Trace";

Optional, single-threaded Iprof timeline recording and a portable binary trace format. Existing Iprof reports are unchanged. Import Iprof separately in manual or plugin mode.

Procedures#

General#

start_captureexperimentalsince 0.36.1Source
(recorder: *Recorder)

Attaches to Iprof before opening zones; only one recorder can be attached. Record frames with Iprof.update(true). Stop at a closed-zone boundary, then save and free the captured trace.

I :: #import "Iprof"(IMPORT_MODE = .CLIENT, MANUAL_MODE = true, USE_GRAPHICS = false);
#import "Extensions/Iprof_Trace";

main :: () {
    recorder: Recorder;
    start_capture(*recorder);
    I.zones[0].name = "work";
    I.zones[0].initted = true;
    I.zone_begin(0);
    I.zone_end();
    I.update(true);
    stop_capture(*recorder);
    assert(save_trace(*recorder.trace, "work.jipt"));
    free_trace(*recorder.trace);
}
↗
stop_captureexperimentalsince 0.36.1Source
(recorder: *Recorder)

Detaches and drops the unfinished frame. All zones must be closed; completed frames remain.

free_traceexperimentalsince 0.36.1Source
(trace: *Trace)

Releases all names, frames and spans; resets trace to an empty value.

Format#

save_traceexperimentalsince 0.36.1Source
(trace: *Trace, path: string) -> bool

Writes JIPT v1: eight-byte magic, little-endian u64 name/frame counts, length-prefixed UTF-8 names, then frames (duration, span count) and spans (zone, parent+1, start, end). Times are ns. Refuses invalid trees and files over 64 MiB. The caller owns the trace.

load_traceexperimentalsince 0.36.1Source
(path: string) -> (Trace, bool)

Loads a bounded JIPT v1 file, validating lengths, indices, containment and sibling order. Returns an empty trace on failure. The successful result owns its storage: use free_trace.

trace, ok := load_trace("work.jipt");
if ok {
    assert(trace.frames.count > 0);
    free_trace(*trace);
}
↗
decode_traceexperimentalsince 0.36.1Source
(bytes: string) -> (Trace, bool)

Decodes bytes with the same validation as load_trace; the result never borrows input memory.

Types#

Spanstructexperimentalsince 0.36.1Source

One invocation, in nanoseconds relative to its frame; parent is a preceding span or -1.

Span :: struct {
    zone: s64;
    parent: s64 = -1;
    start, end: u64;
}
Framestructexperimentalsince 0.36.1Source

A completed frame, including invocation order and nesting (recursive calls stay separate).

Frame :: struct {
    duration: u64;
    spans: [..] Span;
}
Tracestructexperimentalsince 0.36.1Source

Owned zone names and completed frames. Release with free_trace.

Trace :: struct {
    names: [..] string;
    frames: [..] Frame;
}
Recorderstructexperimentalsince 0.36.1Source

Capture storage must stay at the same address until stop_capture. No concurrent profiling.

Recorder :: struct {
    trace: Trace;
    pending: Frame;
    active: [..] s64;
    origin: s64;
    last_tick: s64;
    started: bool;
}