Crate ailloli_ui_bench

Source
Expand description

Versioned JSONL performance recorder for Ailloli UI.

New integrations should retain the BenchInit returned by try_init_from_env and call BenchInit::finish before shutdown. The session writes to a staging file through a bounded queue and publishes the final artifact only after a successful flush and sync.

record and metric remain global conveniences. init_from_env is a deprecated, append-only compatibility path and must not be used for a regression gate.

§Command-line gate

The ailloli-ui-bench binary is intentionally opt-in. Every Cargo command which uses it must enable the cli feature explicitly, for example:

cargo run --release -p ailloli_ui_bench --features cli \
  --bin ailloli-ui-bench --locked -- summarize --input <scenario-directory>

A canonical native matrix first builds the measured child, then gives that executable to the CLI after --:

cargo build --release --locked -p ailloli_ui_winit \
  --features test_support --example winit_regression_bench
cargo run --release --locked -p ailloli_ui_bench --features cli \
  --bin ailloli-ui-bench -- run-matrix \
  --output-root artifacts/bench/winit_host_architecture --phase candidate \
  --winit-version 0.30.13 --backend wayland --profile release \
  --harness winit_regression_bench --scenario wake_single \
  -- target/release/examples/winit_regression_bench

Compare one exact backend/scenario pair at a time. run-matrix writes a matrix-index.json beside each scenario’s replicates; summarize and compare validate that index and every recorded SHA-256 when it is present.

cargo run --release --locked -p ailloli_ui_bench --features cli \
  --bin ailloli-ui-bench -- compare \
  --baseline artifacts/bench/winit_host_architecture/baseline/winit-0.30.13/wayland/wake_single \
  --candidate artifacts/bench/winit_host_architecture/candidate/winit-0.30.13/wayland/wake_single

The only compatibility field which can be waived is winit_version, via an explicit compare --allow-winit-version-diff; schema, scenario, profile, geometry, requested/observed DPR and environment identity remain exact.

There is no valid legacy pre-architecture wake/mailbox baseline: that path did not exist before the refactor. Its historical value is therefore N/A, not a synthetic measurement. The matrix index exposes this status explicitly.

Structs§

BenchConfig
Scripted benchmark parameters read by integration harnesses.
BenchEventRecord
Parsed correlated event line. The payload remains a JSON value so readers can retain events introduced by future schema revisions.
BenchSession
Guard for a single, explicitly finalized benchmark run.
BenchSurfaceId
Stable logical surface identifier used by benchmark correlation.
BenchWindowId
Stable logical window identifier used by benchmark correlation.
CompletedRun
Successfully published benchmark artifact.
EventContext
Correlation attached to a recorded event.
EventId
Monotonic identifier of an event within one run.
FrameId
Identifier of a rendered frame within one run.
MemoryTrendSummary
Deterministic memory-trend decision for a sampled process.
MetadataUpdateRecord
Parsed metadata_update line.
MetricComparison
Regression decision for one metric.
MetricSample
One finite numeric sample together with its explicit regression role.
MetricSummary
Summary of one named metric, including its gate behavior and process count.
ParsedRun
Parsed representation of one run.
ProcessResourceSnapshot
One out-of-band sample of a benchmark process.
Recorder
Legacy append-only JSONL writer.
RunEndRecord
Parsed run_end line.
RunId
Identifier of one benchmark run.
RunMetadata
Reproducibility metadata for one benchmark run.
RunStartRecord
Parsed run_start line.
SampleSummary
Deterministic summary of one finite sample series.
Span
Scoped timing helper; see span.

Enums§

BenchInit
Result of environment-driven benchmark initialization.
BenchInitError
Failure while creating a benchmark session.
BenchReadError
Failure while reading a benchmark artifact.
BenchWriteError
Failure while recording or finalizing a benchmark run.
ComparisonMode
Whether a comparison represents steady-state or cold-start measurements.
Event
One JSONL event payload.
LogRecord
One parsed line from a benchmark artifact.
MetricRole
Regression role carried by an explicit numeric metric.
ProcessSampleError
Failure to obtain an exact process-resource snapshot.
SamplePhase
Classification of a sample for deterministic warmup exclusion.
StatsError
Invalid input for deterministic statistics.
TimeOrigin
Origin used by elapsed-time measurements in a run.

Constants§

MAX_RSS_EXTENT_MIB
Maximum accepted RSS extent after the soak warmup period.
MAX_RSS_SLOPE_MIB_PER_SEC
Maximum accepted RSS growth during a tree virtualization steady-state soak.
SCHEMA_VERSION
Version of the JSONL wire schema emitted by this crate.

Functions§

bench_enabled
Whether benchmark recording is enabled through the environment.
bench_phase_from_env
Bench phase selected through the framework environment namespace.
bench_scenario_from_env
Scenario name selected through the framework environment namespace.
collect_run_files
Recursively finds .jsonl artifacts without following directory symlinks.
compare_metric
Compares two summaries using baseline + max(10%, 3 * baseline MAD).
compare_metric_with_role
Compares two summaries according to the role carried by the metric.
config_from_env
Builds BenchConfig from framework and compatibility environment names.
frames_from_env
Frame count for integration benchmarks (AILLOLI_UI_BENCH_FRAMES, default 60).
init_from_envDeprecated
Enables the historical append-only global recorder.
metadata_from_env
Builds the initial reproducibility metadata snapshot from the environment.
metric
Records a named metric on the global recorder.
metric_with_role
Records a named metric with explicit regression behavior.
read_run
Reads a version-tolerant benchmark JSONL artifact.
record
Records an event on the global recorder. This convenience intentionally ignores errors; gating integrations should call try_record or use the retained BenchSession directly.
sample_current_process
Samples the current process from the operating system’s process interface.
sample_process
Samples RSS, proportional set size, threads, and open descriptors.
span
Starts an RAII timing span recorded as a marker on drop.
summarize_memory_trend
Evaluates the locked tree virtualization RSS slope and extent limits.
summarize_runs
Aggregates samples without exposing gate roles to compatibility callers.
summarize_runs_with_roles
Aggregates all metric samples, roles, and process counts from parsed runs.
summarize_samples
Computes standard median, nearest-rank p95/p99, and median absolute deviation.
theil_sen_slope
Computes the deterministic Theil–Sen slope of (seconds, value) samples.
try_allocate_frame_id
Allocates a frame identifier on the global session. Returns Ok(None) when the recorder is disabled or legacy.
try_init_from_env
Initializes a gating benchmark session from environment variables.
try_record
Attempts to record a globally correlated event.
try_update_metadata
Publishes provider metadata learned after startup on the global session. Returns Ok(false) when the recorder is disabled or legacy.
try_update_window_observation
Publishes the effective winit backend and DPR observed from a live window.