ludus::foundation::profiling¶

Namespace

Declared in modules/foundation/profiling/include/ludus/foundation/profiling/clock.hpp

Constants and variables¶

CALLER_FLOW_ID_BIT¶

constexpr uint64 ludus::foundation::profiling::CALLER_FLOW_ID_BIT = uint64{1} << 63

Set in every caller-supplied flow ID passed to StartFlow and FinishFlow.

LUDUS_PROFILE_FLOW_OUT allocates IDs from a counter that starts at one and never reaches this bit, so the two ID spaces cannot collide. The caller owns uniqueness within its own space for the duration of a capture.

Related types: uint64

Declared in modules/foundation/profiling/include/ludus/foundation/profiling/integration.hpp

PROFILE_CATEGORY_NONE¶

constexpr ProfileCategory ludus::foundation::profiling::PROFILE_CATEGORY_NONE {0u, std::string_view{}}

The "no category" sentinel.

Related types: ProfileCategory

Declared in modules/foundation/profiling/include/ludus/foundation/profiling/zone.hpp

Functions¶

NowTicks¶

uint64 ludus::foundation::profiling::NowTicks() noexcept

Current monotonic timestamp in nanoseconds.

No engine allocations or locks; units do not promise ns resolution. This is the compatibility timestamp entry point on the instrumentation hot path. Timestamps do not establish a happens-before relation between threads.

Related types: uint64

Declared in modules/foundation/profiling/include/ludus/foundation/profiling/clock.hpp

TicksPerNanosecondDenominator¶

uint64 ludus::foundation::profiling::TicksPerNanosecondDenominator() noexcept

Compatibility denominator: always one because exported timestamps remain integer nanoseconds regardless of the underlying physical clock resolution.

Related types: uint64

Declared in modules/foundation/profiling/include/ludus/foundation/profiling/clock.hpp

IsCaptureActive¶

bool ludus::foundation::profiling::IsCaptureActive() noexcept

Whether a capture session is active. One relaxed atomic load; safe before BeginCapture.

Declared in modules/foundation/profiling/include/ludus/foundation/profiling/integration.hpp

RegisterSite¶

void ludus::foundation::profiling::RegisterSite(const ZoneDescriptor &descriptor) noexcept

Records a site's name and source location for export.

Call at most once per descriptor, off the hot path (for example from a function-local static initializer). The registry is bounded; a site beyond its capacity still records events but exports without a name.

Parameter	Description
`descriptor`	Site metadata whose Name and File have static storage duration.

Related types: ZoneDescriptor

Declared in modules/foundation/profiling/include/ludus/foundation/profiling/integration.hpp

BeginSite¶

void ludus::foundation::profiling::BeginSite(uint32 siteId) noexcept

Opens a slice of a registered site on the calling thread.

Pair it with EndSite on the same thread, in last-opened first-closed order.

Parameter	Description
`siteId`	ZoneDescriptor::SiteId of a site registered with RegisterSite.

Related types: uint32

Declared in modules/foundation/profiling/include/ludus/foundation/profiling/integration.hpp

EndSite¶

void ludus::foundation::profiling::EndSite(uint32 siteId) noexcept

Closes the most recently opened slice on the calling thread.

Parameter	Description
`siteId`	The site ID given to the matching BeginSite.

Related types: uint32

Declared in modules/foundation/profiling/include/ludus/foundation/profiling/integration.hpp

StartFlow¶

void ludus::foundation::profiling::StartFlow(const ZoneDescriptor &descriptor, uint64 flowId) noexcept

Starts a flow from the calling thread's innermost open slice.

Exported as a Chrome trace flow start ("s"). Emit it inside an open slice and before the matching FinishFlow can be emitted on any thread.

Parameter	Description
`descriptor`	Registered site naming the flow; FinishFlow must use the same site.
`flowId`	Caller-unique ID with CALLER_FLOW_ID_BIT set.

Related types: uint64 · ZoneDescriptor

Declared in modules/foundation/profiling/include/ludus/foundation/profiling/integration.hpp

FinishFlow¶

void ludus::foundation::profiling::FinishFlow(const ZoneDescriptor &descriptor, uint64 flowId) noexcept

Finishes a flow at the calling thread's innermost open slice.

Exported as a Chrome trace flow end ("f") bound to the enclosing slice.

Parameter	Description
`descriptor`	The site given to the matching StartFlow.
`flowId`	The ID given to the matching StartFlow.

Related types: uint64 · ZoneDescriptor

Declared in modules/foundation/profiling/include/ludus/foundation/profiling/integration.hpp

SampleCounter¶

void ludus::foundation::profiling::SampleCounter(const ZoneDescriptor &descriptor, uint64 value) noexcept

Records a timestamped sample of a counter on the trace timeline.

Exported as a Chrome trace counter event ("C") named by the site. This is a timeline sample in the trace stream, not the planned per-frame aggregated counters and gauges of profiling Phase 2.

Parameter	Description
`descriptor`	Registered site naming the counter.
`value`	Sample value.

Related types: uint64 · ZoneDescriptor

Declared in modules/foundation/profiling/include/ludus/foundation/profiling/integration.hpp

RecordMemoryGauges¶

bool ludus::foundation::profiling::RecordMemoryGauges() noexcept

Records one sample of every registered allocation domain on the calling thread's trace timeline.

Each registered FoundationMemory domain contributes one timestamped group of counter events. ExportPerfettoTrace writes each group as one Chrome trace counter event ("ph":"C") named Memory/<domain> whose arguments are the domain's Validity, LiveRequestedBytes, LiveBlocks, PeakRequestedBytes, AllocatedBytes, FreedBytes, AllocationCount, FreeCount, FailureCount and RejectedCount. A domain whose accounting is no longer valid contributes only Validity (1 saturated, 2 accounting error), never plausible-looking byte values. The export's metadata object carries the coverage manifest: the sampled domains and the allocation paths outside domain accounting.

Values are relaxed per-field samples. They reconcile exactly only when the caller has established that no thread is inside an allocation or free in any registered domain for the duration of this call; this function cannot detect a violation. Per-domain peaks are separate histories; viewers must not sum them into a process peak.

Gauge events share the capture's bounded event pool: a dropped event omits its metric from that sample and is counted in TraceHealth::EventsDropped. Never allocates and never blocks beyond the recorder's per-chunk lock.

Returns

True when a capture is active and every event of the sample was recorded; false when no capture is active, in a profiling-disabled browser build, or when any event was dropped.

Note

Call from a thread registered with RegisterThreadForTrace so the sample is attributed and flushed. Domain accounting itself is independent of LUDUS_PROFILING_ENABLED and of whether a capture is active.

Declared in modules/foundation/profiling/include/ludus/foundation/profiling/memory_gauges.hpp

SerializePerfettoTrace¶

bool ludus::foundation::profiling::SerializePerfettoTrace(Array< uint8 > &outBytes, BorrowedView< const GpuTraceSample > samples={}, const GpuTraceCoverage &coverage={}, bool shouldIncludeCpu=true) noexcept

Serialize a stopped recording into owned Chrome/Perfetto JSON bytes, off the hot path.

Parameter	Description
`outBytes`	Receives the complete file bytes only on success; unchanged on failure.
`samples`	Borrowed completed GPU samples, consumed during this call. IDs must be nonzero and CollectionTicks must not precede SubmissionTicks. PassName must be valid UTF-8 without embedded zero; ScopeIdentity must be nonzero exactly when PassName is nonempty. An execution interval requires a named pass and must not end before it starts. Calibrated passes are also emitted as named "X" slices on GPU execution lanes; overlapping passes use separate lanes rather than inventing nesting. No native objects are retained.
`coverage`	GPU sampling coverage included in the exported artifact.
`shouldIncludeCpu`	When true, drains the most recent stopped CPU recording. When false, does not drain CPU events or serialize CPU thread metadata, allowing GPU-only export without enabling CPU scopes.

Returns

False for invalid samples, active CPU capture, empty data, disabled profiling or output-buffer allocation failure. Drained CPU events are consumed if a later step fails. Flattening and JSON assembly retain the existing exporter's allocation policy.

Note

Serialize capture lifecycle/export calls. Preserve successful bytes for I/O retry; never start a new CPU capture until the application's unexported recording is resolved.

Related types: BorrowedView · Array · uint8 · GpuTraceCoverage · GpuTraceSample

Declared in modules/foundation/profiling/include/ludus/foundation/profiling/perfetto_export.hpp

RegisterThreadForTrace¶

void ludus::foundation::profiling::RegisterThreadForTrace(std::string_view threadName) noexcept

Register the calling thread with the tracer so its events are attributed and its partial chunk is flushed on exit.

Assigns a stable profiling-local thread id and records the human-readable name for export. Safe to call before BeginCapture. Idempotent per thread. (Profiling keeps its own thread identity rather than depending on the logging module, preserving the FoundationBase-only dependency direction — AGENTS.md.)

Declared in modules/foundation/profiling/include/ludus/foundation/profiling/trace_system.hpp

UnregisterThreadForTrace¶

void ludus::foundation::profiling::UnregisterThreadForTrace() noexcept

Unregister the calling thread (publishes its partial chunk).

Optional — thread destruction does this automatically.

Declared in modules/foundation/profiling/include/ludus/foundation/profiling/trace_system.hpp

BeginCapture¶

bool ludus::foundation::profiling::BeginCapture(usize maxChunks=64) noexcept

Arm a capture session.

Reserves one slab of maxChunks 64-byte-aligned chunks (about 96 KiB each; zero is treated as one) so recording never allocates. Events of a previous capture that were not exported are discarded.

Parameter	Description
`maxChunks`	Bound on total trace memory, in chunks.

Returns

False when a capture is already active, the slab size overflows usize, or the reservation fails; tracing then stays disabled and the engine runs normally (§21).

Note

Capture control calls (Begin/End/Export) must be serialized by the caller. Producer threads may keep emitting events across them.

Related types: usize

Declared in modules/foundation/profiling/include/ludus/foundation/profiling/trace_system.hpp

EndCapture¶

void ludus::foundation::profiling::EndCapture() noexcept

End the active capture session and join its producers.

Disarms recording, waits for threads that are writing an event, and publishes every thread's partial chunk, so all events accepted before this returns are available to ExportPerfettoTrace(), including those of threads that are still running. Safe to call when no capture is active.

Note

Waits only for an in-progress event write; a producer thread suspended in the middle of one delays the return.

Declared in modules/foundation/profiling/include/ludus/foundation/profiling/trace_system.hpp

HasUnexportedTrace¶

bool ludus::foundation::profiling::HasUnexportedTrace() noexcept

Whether a stopped CPU recording still has published events awaiting serialization/export. Does not drain or discard data. Serialize this control query with Begin/End/Export; active producers may still hold unpublished events, so this is not an active-capture test.

Declared in modules/foundation/profiling/include/ludus/foundation/profiling/trace_system.hpp

ExportPerfettoTrace¶

bool ludus::foundation::profiling::ExportPerfettoTrace(std::string_view path) noexcept

Serialise the most recent capture to a Chrome/Perfetto trace-event JSON file (final design §16 primary viewer path).

Off the hot path. Returns false on I/O failure or when nothing was captured. Safe no-op in a disabled build. On web this writes the Emscripten virtual filesystem (normally in-memory MEMFS), not a persistent host file. The application must explicitly download the bytes before page teardown; see tools/web-observability-probe/shell.html.

Declared in modules/foundation/profiling/include/ludus/foundation/profiling/trace_system.hpp

GetTraceHealth¶

TraceHealth ludus::foundation::profiling::GetTraceHealth() noexcept

Related types: TraceHealth

Declared in modules/foundation/profiling/include/ludus/foundation/profiling/trace_system.hpp

HashZoneName¶

constexpr uint32 ludus::foundation::profiling::HashZoneName(std::string_view name) noexcept

Compile-time FNV-1a (32-bit) — identical construction to the logging category hash, kept independent so the two subsystems do not couple.

Used for both site ids and category ids (C3).

Related types: uint32

Declared in modules/foundation/profiling/include/ludus/foundation/profiling/zone.hpp

ludus::foundation::profiling¶

Related declarations¶

Constants and variables¶

CALLER_FLOW_ID_BIT¶

PROFILE_CATEGORY_NONE¶

Functions¶

NowTicks¶

TicksPerNanosecondDenominator¶

IsCaptureActive¶

RegisterSite¶

BeginSite¶

EndSite¶

StartFlow¶

FinishFlow¶

SampleCounter¶

RecordMemoryGauges¶

SerializePerfettoTrace¶

RegisterThreadForTrace¶

UnregisterThreadForTrace¶

BeginCapture¶

EndCapture¶

HasUnexportedTrace¶

ExportPerfettoTrace¶

GetTraceHealth¶

HashZoneName¶