From e105b8514bd5a2f832aa570994956b26b680ab4e Mon Sep 17 00:00:00 2001 From: Thomas Korrison Date: Mon, 27 Apr 2026 14:11:07 +0100 Subject: [PATCH] docs: enhance benchmark documentation with value construction convention - Added a section on value construction convention to the benchmark files, clarifying how benchmark entry points utilize `Fn(u64) -> Arc` for value storage. - Emphasized the importance of using the cheapest possible payload to focus on cache policy behavior rather than allocator costs. These updates improve the clarity of benchmark usage and ensure users understand the implications of value construction on performance metrics. --- benches/reports.rs | 9 +++++++++ benches/runner.rs | 9 +++++++++ benches/workloads.rs | 9 +++++++++ 3 files changed, 27 insertions(+) diff --git a/benches/reports.rs b/benches/reports.rs index 0d22714..c855bb6 100644 --- a/benches/reports.rs +++ b/benches/reports.rs @@ -2,6 +2,15 @@ //! //! This is a standalone binary (not a criterion benchmark) that prints //! human-readable comparison tables for cache policy evaluation. +//! +//! ## Value construction convention +//! +//! Benchmark entry points take a `value_for_key: Fn(u64) -> Arc` so callers +//! choose what to store. We pass [`Arc::new`] directly, which the compiler +//! resolves to `fn(u64) -> Arc`, i.e. the value is the key itself wrapped +//! in `Arc`. Cache-policy measurements (hit/miss, eviction, latency) don't +//! depend on payload contents, so the cheapest possible payload keeps the +//! workload focused on policy behavior rather than allocator/clone cost. use bench_support as common; use bench_support::for_each_policy; diff --git a/benches/runner.rs b/benches/runner.rs index 279fccd..21225ac 100644 --- a/benches/runner.rs +++ b/benches/runner.rs @@ -4,6 +4,15 @@ //! JSON results to `target/benchmarks//results.json`. //! //! Run with: `cargo bench --bench runner` +//! +//! ## Value construction convention +//! +//! Benchmark entry points take a `value_for_key: Fn(u64) -> Arc` so callers +//! choose what to store. We pass [`Arc::new`] directly, which the compiler +//! resolves to `fn(u64) -> Arc`, i.e. the value is the key itself wrapped +//! in `Arc`. Cache-policy measurements (hit/miss, eviction, latency) don't +//! depend on payload contents, so the cheapest possible payload keeps the +//! workload focused on policy behavior rather than allocator/clone cost. use bench_support as common; use bench_support::for_each_policy; diff --git a/benches/workloads.rs b/benches/workloads.rs index 53178dd..acd6816 100644 --- a/benches/workloads.rs +++ b/benches/workloads.rs @@ -11,6 +11,15 @@ //! For micro-ops (get/insert latency), see: `cargo bench --bench ops` //! For policy-specific operations, see: `cargo bench --bench policy_*` //! For external crate comparison, see: `cargo bench --bench comparison` +//! +//! ## Value construction convention +//! +//! Benchmark entry points take a `value_for_key: Fn(u64) -> Arc` so callers +//! choose what to store. We pass [`Arc::new`] directly, which the compiler +//! resolves to `fn(u64) -> Arc`, i.e. the value is the key itself wrapped +//! in `Arc`. Cache-policy measurements (hit/miss, eviction, latency) don't +//! depend on payload contents, so the cheapest possible payload keeps the +//! workload focused on policy behavior rather than allocator/clone cost. use bench_support as common; use bench_support::for_each_policy;