Module profiling 

Frame profiler and headless performance-testing harness for ui apps.

Measures each of the toolkit’s five frame passes (sync, build_layout, apply_layout, draw, handle_event — see crate::widget::Widget) so frame cost can be read off, not guessed. Three surfaces share one type (FrameTiming): an in-app HUD (TILO_PROFILE=1, hooked into crate::app::App’s render loop with no per-app code), a machine-readable dump (TILO_PROFILE_OUT=<path>, JSON-lines or CSV, plus a tracing event under tilo::profile per frame), and a headless perf harness (run_scenario) that drives a scripted PerfScenario through the app’s real widget passes with no GPU or display and returns a PerfReport a test can assert on.

When neither env var is set, FrameProfiler::from_env returns None and the render-loop hooks are Option::map over that: no clock read, no allocation, until profiling is explicitly requested.

Live-frame diagnostics also attribute resource availability, recycled-buffer waiting, and presence overlays. Waiting is wall time, not active CPU work; none of these fields measure GPU completion or display presentation.

Structs

FrameProfiler

The crate::app::App holds one of these behind an Option; the headless crate::headless::FrameHarness holds another for the perf harness. Both feed it the same way: record a pass duration, then commit_frame once per frame.

FrameTiming

This is the atom every surface shares: the HUD graphs it, the dump serialises it, and PerfReport aggregates it.

PerfReport

Per-pass and total statistics over every frame a PerfScenario produced, plus how many blew the frame budget.

PerfScenario

Reusable across any app: build a crate::headless::FrameHarness over the app’s real root + state, then call run_scenario.

StatSummary

For one column of measurements (a single pass, or the total), in microseconds.

Enums

Pass

Attributes a measured duration to the right column of the current frame’s FrameTiming.

PerfStep

Each step drives the headless driver and produces one or more measured frames.

Constants

FRAME_BUDGET_US

Rounded 60 Hz CPU-work budget. Exceeding it is a CPU diagnostic, not evidence of an actual dropped display frame.

Functions

run_scenario

The driver runs the app’s real five passes with no GPU or display, so timings are of the production code path, not a mock.

run_scenario_on

The one-call entry point for an app author or a test: no driver bookkeeping.