Skip to main content

perf/
perf.rs

1// SPDX-License-Identifier: Apache-2.0
2// SPDX-FileCopyrightText: Copyright 2026 avatarsd LLC
3/*!
4 * @brief Rust codec perf bench — the `lang` axis (Rust core) of the ranged cross-core
5 * perf matrix (ADR-0032, issue #96). It measures decode+encode roundtrip latency
6 * and throughput over the SHARED conformance vectors under
7 * tests/conformance/vectors/v1/ (the "vector data" workload — real structured
8 * TLVs, not synthetic scalars), so a C++-vs-TS-vs-Rust surface can be rendered
9 * over the SAME inputs.
10 *
11 * Output: one machine-parseable RESULT line per vector, in the SAME
12 * tab-separated column contract as the C++ bench (bench/bench_common.hpp) and the
13 * TS bench (bindings/typescript/packages/core/bench/perf.mjs):
14 *
15 *   RESULT \t system \t mode \t size \t fanout \t endpoints \t pub_s \t
16 *          deliv_s \t mb_s \t p50ns \t p99ns \t meanns
17 *
18 * with system="rust-core", mode="codec", fanout=1, endpoints=1. pub_s and deliv_s
19 * are roundtrips/sec (one roundtrip == one decode + one encode); mb_s is
20 * bytes/sec/1e6; p50/p99/mean are per-roundtrip nanoseconds. A human-readable
21 * per-vector ns/op footer follows on stderr for readability.
22 *
23 * Run headlessly with the release profile (representative numbers):
24 *   cargo run --release --example perf -- tests/conformance/vectors/v1
25 * The vectors dir is taken from argv, else defaults relative to CARGO_MANIFEST_DIR
26 * (mirrors examples/conformance.rs).
27 */
28
29use std::hint::black_box;
30use std::path::{Path, PathBuf};
31use std::time::Instant;
32
33use libtracer::{decode, encode};
34
35/** @brief Target per-vector throughput-phase wall time, so each ns/op is stable. */
36const TARGET_NS: u128 = 100_000_000; // 100 ms throughput phase
37const LATENCY_SAMPLES: usize = 20_000; // individual timed roundtrips for percentiles
38const WARMUP: usize = 5_000;
39const PROBE_N: usize = 2_000;
40
41/**
42 * @brief One decode+encode roundtrip on the given bytes (the unit of work). The result
43 * is fed through `black_box` so the optimizer cannot elide the work.
44 */
45fn roundtrip(input: &[u8]) {
46    let tlv = decode(input).expect("conformance vector must decode");
47    black_box(encode(black_box(&tlv)));
48}
49
50struct Measure {
51    pub_s: f64,
52    mb_s: f64,
53    p50: u64,
54    p99: u64,
55    mean: u64,
56}
57
58/**
59 * @brief Measure a single vector: a tight throughput loop (>= TARGET_NS) for the rate,
60 * then a batch of individually-timed roundtrips for the latency percentiles.
61 */
62fn measure(input: &[u8]) -> Measure {
63    // Warm up branch predictors / caches before any timing.
64    for _ in 0..WARMUP {
65        roundtrip(input);
66    }
67
68    // Calibrate iteration count from a short probe so the timed loop ~= TARGET_NS.
69    let t0 = Instant::now();
70    for _ in 0..PROBE_N {
71        roundtrip(input);
72    }
73    let probe = t0.elapsed().as_nanos().max(1);
74    let per_op = (probe / PROBE_N as u128).max(1);
75    let mut iters = (TARGET_NS / per_op) as usize;
76    if iters < PROBE_N {
77        iters = PROBE_N;
78    }
79    if iters > 50_000_000 {
80        iters = 50_000_000;
81    }
82
83    // Throughput phase: one tight loop, measure total wall time.
84    let t0 = Instant::now();
85    for _ in 0..iters {
86        roundtrip(input);
87    }
88    let secs = t0.elapsed().as_nanos() as f64 / 1e9;
89    let pub_s = iters as f64 / secs;
90    let mb_s = (iters as f64 * input.len() as f64) / secs / 1e6;
91
92    // Latency phase: time individual roundtrips for the percentiles.
93    let mut samples = vec![0u64; LATENCY_SAMPLES];
94    for s in samples.iter_mut() {
95        let start = Instant::now();
96        roundtrip(input);
97        *s = start.elapsed().as_nanos() as u64;
98    }
99    samples.sort_unstable();
100    let at = |p: f64| -> u64 {
101        let idx = ((p * samples.len() as f64) as usize).min(samples.len() - 1);
102        samples[idx]
103    };
104    let sum: u128 = samples.iter().map(|&v| v as u128).sum();
105    let mean = (sum / samples.len() as u128) as u64;
106
107    Measure {
108        pub_s,
109        mb_s,
110        p50: at(0.5),
111        p99: at(0.99),
112        mean,
113    }
114}
115
116/** @brief Recursively collect (relative-posix-path, absolute-path) for every input.bin. */
117fn find_inputs(root: &Path, dir: &Path, out: &mut Vec<(String, PathBuf)>) {
118    let mut entries: Vec<PathBuf> = match std::fs::read_dir(dir) {
119        Ok(rd) => rd.filter_map(|e| e.ok().map(|e| e.path())).collect(),
120        Err(_) => return,
121    };
122    entries.sort();
123    for p in entries {
124        if p.is_dir() {
125            find_inputs(root, &p, out);
126        } else if p.file_name().map(|n| n == "input.bin").unwrap_or(false) {
127            let rel = p
128                .parent()
129                .unwrap()
130                .strip_prefix(root)
131                .unwrap()
132                .components()
133                .map(|c| c.as_os_str().to_string_lossy())
134                .collect::<Vec<_>>()
135                .join("/");
136            out.push((rel, p));
137        }
138    }
139}
140
141/** @brief Default vectors dir relative to CARGO_MANIFEST_DIR (mirrors conformance.rs). */
142fn default_vectors_dir() -> PathBuf {
143    Path::new(env!("CARGO_MANIFEST_DIR")).join("../../tests/conformance/vectors/v1")
144}
145
146fn main() {
147    let args: Vec<String> = std::env::args().skip(1).collect();
148    let vectors_dir = args
149        .iter()
150        .find(|a| !a.starts_with("--"))
151        .map(PathBuf::from)
152        .unwrap_or_else(default_vectors_dir);
153
154    // Sort by POSIX relative path so the row order matches the C++/TS harnesses.
155    let mut cases: Vec<(String, PathBuf)> = Vec::new();
156    find_inputs(&vectors_dir, &vectors_dir, &mut cases);
157    cases.sort_by(|a, b| a.0.cmp(&b.0));
158
159    if cases.is_empty() {
160        eprintln!("no input.bin vectors found under {}", vectors_dir.display());
161        std::process::exit(2);
162    }
163
164    let mut rows: Vec<(String, usize, Measure)> = Vec::with_capacity(cases.len());
165    for (rel, abs) in &cases {
166        let input = std::fs::read(abs).expect("read input.bin");
167        let m = measure(&input);
168        // RESULT line — identical column contract to bench_common.hpp emit() /
169        // perf.mjs: system="rust-core", mode="codec", fanout=1, endpoints=1.
170        // pub_s == deliv_s (roundtrips/sec); mb_s = bytes/sec/1e6.
171        println!(
172            "RESULT\trust-core\tcodec\t{}\t1\t1\t{:.0}\t{:.0}\t{:.1}\t{}\t{}\t{}",
173            input.len(),
174            m.pub_s,
175            m.pub_s,
176            m.mb_s,
177            m.p50,
178            m.p99,
179            m.mean,
180        );
181        rows.push((rel.clone(), input.len(), m));
182    }
183
184    // Human-readable footer (per-vector ns/op), to stderr so RESULT stdout stays
185    // clean for collate.py-style tooling.
186    eprintln!(
187        "\n# rust-core codec bench — {} vectors ({})",
188        rows.len(),
189        vectors_dir.display()
190    );
191    eprintln!(
192        "# {:<34}{:>7}{:>12}{:>9}{:>9}{:>10}",
193        "vector", "size", "ns/op", "p50", "p99", "M op/s"
194    );
195    for (rel, size, m) in &rows {
196        eprintln!(
197            "# {:<34}{:>7}{:>12}{:>9}{:>9}{:>10}",
198            rel,
199            format!("{}B", size),
200            m.mean,
201            m.p50,
202            m.p99,
203            format!("{:.2}", m.pub_s / 1e6),
204        );
205    }
206}