perf-check

name

perf-check

description

Measure latexml-oxide conversion performance correctly, pick the right build profile, and avoid re-litigating settled optimization questions. Use when benchmarking, comparing against Perl, choosing a profile, diagnosing a slow/OOM conversion, or when tempted to optimize startup/codegen. Invoke for "is this slower?", "benchmark X", "which profile", "optimize startup", "profile this paper", "/perf-check".

Build profiles — use the right one (Cargo.toml)

Profile	Command	Use
test (default)	cargo build / cargo test / cargo run	All day-to-day dev + triage. Full debug info, debug-assertions, overflow-checks, fast incremental. Best diagnosability.
ci	cargo test --profile ci	GitHub runner only (16 GB, fast compile). NOT what local dev should mimic.
release	cargo build --release	Sandbox sweeps + Perl-parity measurement. Strong-optimized, thin-LTO.
maxperf	cargo build --profile maxperf	Distribution artifact. Fat-LTO, CGU=1, panic=abort. Slowest build; smallest+fastest binary.

Distribution recipe (what tools/make_release.sh uses): cargo build --no-default-features --features runtime-bindings --profile maxperf --bin latexml_oxide.

Settled questions — DO NOT re-open (measured, closed, tooling deleted)

• PGO / target-cpu (x86-64-v3, native): NO measurable gain. Rigorous measurement (2026-06-21, disjoint train/measure split, best-of-3 interleaved): total speedup 0.999×, identical medians. maxperf is already at the compiler ceiling (fat-LTO + CGU=1 captures what PGO would unlock on thin-LTO), and the hot path (branchy catcode/macro dispatch) is neither SIMD-amenable nor statically branch-skewed. Ship the portable x86-64 baseline. Do not re-attempt without a major engine-architecture change. (pgo-isa-no-gain-2026-06-21 memory; docs/performance/PERFORMANCE.md.)
• Startup floor (~161 ms): the ~50 ms dump-parse lever was declined. Decomposed: proc init ~6 ms, bootstrap ~9 ms, latex dump load ~85 ms (60% text-parse), _constructs+digest+build+serialize ~80 ms. The clean lever (binary dump format / parallel-parse) is ~50 ms ≈ 10% of the 507 ms median — declined as too small to justify the dump-pipeline parity re-validation risk. Compiling dumps to Rust code (vs gzip-blob embed) cost +10 min compile for zero win, abandoned. Do not optimize the dump load. (docs/archive/STARTUP_COST_ANALYSIS_2026-06-21.md.)

Measurement discipline (this is where perf claims go wrong)

• Same-conditions A/B only. A one-off wall-clock reading on an idle vs busy machine is noise — we once read 0.65 s and retracted a "5× faster" claim once a same-conditions before/after showed ~3.35 s → ~3.1 s (no real change). Always measure base and candidate back-to-back under the same load; prefer best-of-3 interleaved on a quiesced box.
• Tools: tools/perf_compare.py (paired A/B of two telemetry corpus runs: Δwall, Δphase_us), tools/perf_phase_summary.py (per-phase rollups), tools/run_perf_corpus.sh (Tier-A serial regression baseline). Full methodology + Perl-parity baselines: docs/performance/PERFORMANCE.md. Witness papers for timeout/OOM/peak-RSS/hang regressions: docs/performance/STABILITY_WITNESSES.md.

Test-suite gotcha: MemoryBudget cascade ≠ code bug

A cascade of failures on basic documents (article/book/itemize) that pass at --test-threads=1 is the process-wide RSS fuse (stomach.rs::check_timeout, Fatal:Timeout:MemoryBudget RSS … > cap), not a regression. libtest runs one process with one thread per test, so on this 64-core/128-thread box -j128 runs ~128 conversions whose aggregate RSS trips the fuse. The default cap stays 4.5 GB (a parallel one-paper-per-process fleet would OOM at 9 GB); the test harness raises it to 9 GB via init_test_rss_cap(). Diagnosis: re-run with -- --test-threads=1; a non-<Math> fixture failing is another tell a MathML change is innocent. Always use cargo test --workspace --tests --no-fail-fast for the true count (default fail-fast stops at the first failing binary). (cargo-test-rss-fuse-parallelism memory.)

Self-contained-binary invariant (a correctness-of-distribution check)

A conversion must not read latexml-oxide's own resources from disk at runtime — dumps, RelaxNG schema, XSLT/CSS/JS are embedded and served from memory. New code that adds a runtime read of an owned resource must include_bytes!/ include_str! it instead. (Reading the host texmf tree via kpathsea is allowed.) Verify by renaming resources/dumps/ away and converting, or strace for the XSLT. Rationale: docs/parity/OXIDIZED_DESIGN.md → Guiding Principles.