From 244023605536a412ab6b8d5b658466b89fb15401 Mon Sep 17 00:00:00 2001
From: Anthony Eid <56899983+Anthony-Eid@users.noreply.github.com>
Date: Mon, 28 Sep 2026 13:02:30 +0000
Subject: [PATCH] gpui: Add seeded benchmarks and heap allocation metrics
(#64843)
Two additions to GPUI's benchmark harness, split out of #64842 so the
randomized element tree harness can build on them.
## Seeded `#[gpui::bench]` benchmarks
A benchmark that takes a `StdRng` parameter runs once per seed, and each
seed is its own Criterion benchmark named `/seed-` (or
`/seed-` without inputs). Seeds come from
`calculate_seeds`, moved out of `test.rs` into `seeds.rs` so it compiles
under `bench-support` and is shared with `#[gpui::test]`. `seed = N`,
`seeds(...)`, `iterations = N`, `SEED` and `ITERATIONS` therefore mean
the same in tests and benchmarks, and one `SEED` reproduces either. The
RNG is rebuilt on every Criterion routine call, so warm-up and every
sample measure the same workload. The generated code seeds it through
`gpui::private::rand`, so a bench crate needs `rand` only to name
`StdRng` in its signature.
```rust
#[gpui::bench(inputs = families(), input_name = "tree", iterations = 6)]
fn full_refresh(family: &Family, mut rng: StdRng, cx: &mut BenchAppContext) { ... }
```
The macro now also checks the benchmark's parameters, and reports a
wrong parameter count, a `&mut StdRng`, or `seed`/`seeds`/`iterations`
without a `StdRng` parameter as clear errors.
**Behavior change in `gpui::test`:** with `SEED` set and `iterations >
1`, `calculate_seeds` returned `SEED` and then `SEED..SEED+iterations`,
so `SEED=7 ITERATIONS=2` ran 7, 7, 8. Criterion rejects the duplicate
benchmark ID, and the function's comment already described
`SEED..SEED+iterations`, so it now runs 7, 8.
## Heap allocation metrics in `bench_metrics`
- `CountingAllocator` wraps any global allocator and counts
allocations, allocated bytes and freed bytes in sharded relaxed atomics,
with no backtraces. Each thread also counts its own allocations in plain
thread-locals.
- `AllocationCounter` measures allocations or allocated bytes per
iteration over a `MetricScope`, like `HardwareCounter`. When the
allocator is installed, `allocations`, `foreground allocations` and
`allocated bytes` are default secondaries.
`BENCH_MEASUREMENT=allocations` or `foreground-allocations` makes one of
them the primary. Without the allocator they're skipped with a one-time
note, like unavailable hardware counters.
- `foreground allocations` leaves out background workers' timing noise.
It can still vary between samples when the workload does, for example
when frames coalesce or caches grow in early samples, so a CI gate on it
needs a small tolerance.
- `allocation_stats()` exposes the totals and `live_bytes()` for heap
held around setup and teardown.
- `gpui::bench_main!` installs `CountingAllocator` over the system
allocator. `gpui::bench_main!(allocator = mimalloc::MiMalloc; benches)`
wraps another allocator instead, and `allocator = none;` installs
nothing.
Example, `inspector_render` smallest case: `allocations per iteration:
median 558`, `allocated bytes per iteration: median 390 K`.
## Notes for reviewers
- The counting allocator is installed in every GPUI bench binary. It
adds a few relaxed atomic increments per allocation, so wall-time
baselines saved before this PR shift slightly.
- Placements in GPUI's element arena aren't heap allocations, so they
aren't counted once the arena is warm. Arena bytes per iteration could
be a GPUI secondary in a follow-up.
## Validation
- Throwaway seeded bench (inputs `a`/`b`, `iterations = 2`,
`seeds(40)`): correct seed order by default and with `SEED=7`, `SEED=7
ITERATIONS=2`, `ITERATIONS=3`; every routine call drew the same first
value for a seed; the allocations primary reported exactly 1 allocation
/ 64 bytes per iteration for `vec![0u8; 64]`. A second throwaway bench
imported `StdRng` through `gpui::private::rand` with no `rand`
dependency of its own and ran `probe/seed-0` and `probe/seed-1`.
- `inspector_render` ran with the default allocator and with `allocator
= none;` (which prints the note and reports no allocation lines), and
built with `allocator = std::alloc::System;`.
- New unit tests for seed order, process-wide allocation counting, and
exact calling-thread counts that exclude other threads; `bench_metrics`
and `bench_context` tests pass.
- `./script/clippy` and `cargo fmt` clean; `--no-run` builds of
`gpui_platform` and `benchmarks` benches.
Release Notes:
- [GPUI] Added seeded `#[gpui::bench]` benchmarks that take a `StdRng`,
and heap allocation counts in benchmark reports
---
.agents/skills/gpui-bench/SKILL.md | 19 +-
crates/bench_metrics/src/bench_metrics.rs | 463 +++++++++++++++++++++-
crates/gpui/src/app.rs | 4 +-
crates/gpui/src/app/bench_context.rs | 2 +-
crates/gpui/src/gpui.rs | 32 +-
crates/gpui/src/seeds.rs | 67 ++++
crates/gpui/src/test.rs | 50 +--
crates/gpui_macros/src/bench.rs | 220 ++++++++--
crates/gpui_macros/src/gpui_macros.rs | 18 +
9 files changed, 759 insertions(+), 116 deletions(-)
create mode 100644 crates/gpui/src/seeds.rs
diff --git a/.agents/skills/gpui-bench/SKILL.md b/.agents/skills/gpui-bench/SKILL.md
index 8a1a2777835..b54eebe1bcb 100644
--- a/.agents/skills/gpui-bench/SKILL.md
+++ b/.agents/skills/gpui-bench/SKILL.md
@@ -132,9 +132,19 @@ The attribute supports options such as:
Inspect the current macro before depending on an option because the API is evolving.
-Register benchmark functions with `gpui::bench_group!` and `gpui::bench_main!` (drop-in for Criterion's `criterion_group!`/`criterion_main!`, including the `name = ...; config = ...; targets = ...` form). The generated functions take `&mut criterion::Criterion`; `bench_group!` supplies that measurement from the environment.
+For randomized workloads, take a `StdRng` parameter (by value) and draw the workload from it instead of hand-rolling seeds. The macro then runs one Criterion benchmark per seed, named `/seed-`, with `seed = N`, `seeds(...)`, `iterations = N`, `SEED`, and `ITERATIONS` meaning exactly what they do for `#[gpui::test]`, so `SEED=3` reproduces the same workload in a test and a benchmark. The RNG is rebuilt for every Criterion routine call, so warm-up and every sample see the same workload.
-### Measurements: wall time, hardware counters, and rusage
+```rust
+#[gpui::bench(inputs = tree_families(), input_name = "tree", iterations = 6)]
+fn full_refresh(family: &TreeFamily, mut rng: StdRng, cx: &mut gpui::BenchAppContext) {
+ let tree = family.sample(&mut rng);
+ // ...
+}
+```
+
+Register benchmark functions with `gpui::bench_group!` and `gpui::bench_main!` (drop-in for Criterion's `criterion_group!`/`criterion_main!`, including the `name = ...; config = ...; targets = ...` form). The generated functions take `&mut criterion::Criterion`; `bench_group!` supplies that measurement from the environment. `bench_main!` also installs `gpui::CountingAllocator` as the binary's global allocator, so a GPUI bench file must not declare its own `#[global_allocator]`; to measure with another allocator, write `gpui::bench_main!(allocator = mimalloc::MiMalloc; benches)`, which wraps it. `allocator = none;` installs no allocator and drops the allocation metrics.
+
+### Measurements: wall time, hardware counters, rusage, and allocations
`gpui::BenchMeasurement` (from the gpui-independent `bench_metrics` crate) records several metrics per Criterion sample. Criterion analyzes one of them (the *primary*, shown on its `time:` line with confidence intervals and baseline comparison); the rest are *secondaries*, printed per iteration in the GPUI bench report as median/min/max. `BENCH_MEASUREMENT` selects the arrangement:
@@ -143,6 +153,8 @@ Register benchmark functions with `gpui::bench_group!` and `gpui::bench_main!` (
| unset (default) | wall time | every counter the machine supports (below) |
| `instructions` | process-wide retired instructions; fails fast if counters are unavailable | the rest, plus wall time |
| `foreground-instructions` | the benchmark thread's retired instructions; fails fast if unavailable | the rest, plus wall time |
+| `allocations` | process-wide heap allocations; fails fast without `CountingAllocator` | the rest, plus wall time |
+| `foreground-allocations` | the benchmark thread's heap allocations, without background workers' timing noise; fails fast without `CountingAllocator` | the rest, plus wall time |
| `wall-time` | wall time | nothing; no counters are opened |
For a CI gate on frame cost prefer `foreground-instructions`: it excludes background parsing and GPU-driver submission threads, whose work varies run to run, and on Apple Silicon the process-wide count includes driver jitter that widens the interval (about ±0.6% versus ±0.01% for the foreground thread).
@@ -154,6 +166,7 @@ Default secondaries, each skipped with a one-time note when unavailable:
- **branch misses** and **cache misses** (last-level), for diagnosing an IPC drop. Linux only.
- **foreground context switches**: voluntary switches on the benchmark thread per iteration, i.e. how many times a frame blocked on a lock, channel, or fence. This is the metric that catches the waits instructions cannot see. Linux only.
- **page faults**: minor faults per iteration, a privilege-free proxy for fresh memory touched.
+- **allocations**, **foreground allocations**, and **allocated bytes**: heap allocations (reallocations count as one each) across every thread and on the benchmark thread alone, and the bytes requested across every thread, per iteration. Background workers allocate on their own schedule, so the foreground count excludes that noise. It can still vary between samples when the workload does, e.g. frames coalescing or caches growing in early samples, so a CI gate needs a small tolerance. Arena placements (GPUI's element arena) are not heap allocations and are not counted once the arena is warm. Needs `bench_metrics::CountingAllocator` as the global allocator, which `gpui::bench_main!` installs; it wraps any allocator (`CountingAllocator`) and costs a few relaxed atomics per allocation. For heap held between iterations, read `bench_metrics::allocation_stats()` before and after setup; `live_bytes()` is allocated minus freed.
Run one benchmark process per machine at a time. Hardware counters are per task, so instruction counts stay correct next to a concurrent `cargo bench`, but wall time, IPC, and cache misses share the hardware and degrade, and two processes requesting counters can exceed a core's counter slots, at which point the kernel multiplexes and the counts become scaled estimates (a warning is printed once). Within one process, benchmarks already run sequentially; process-wide counters can still attribute a previous benchmark's trailing background work to the next benchmark's first sample, which the foreground-thread metrics are immune to.
@@ -182,7 +195,7 @@ group.bench_function("append", |b| report.iter(b, || rope.append(small.clone()))
report.print(" ");
```
-Criterion's `Throughput` lines keep working alongside. Page faults per iteration are a useful allocation-pressure signal for data-structure crates even without a counting allocator.
+Criterion's `Throughput` lines keep working alongside. Page faults per iteration are a useful allocation-pressure signal even without a counting allocator; for exact counts, install `bench_metrics::CountingAllocator` as the binary's `#[global_allocator]`.
### `bench_iter`: synchronous functions and compute work
diff --git a/crates/bench_metrics/src/bench_metrics.rs b/crates/bench_metrics/src/bench_metrics.rs
index 3d157b629d3..1ec628b0e94 100644
--- a/crates/bench_metrics/src/bench_metrics.rs
+++ b/crates/bench_metrics/src/bench_metrics.rs
@@ -6,8 +6,9 @@
//! measurements taken over the same iterations, whose per-iteration values a
//! benchmark harness records into a [`MetricReport`]. The measurements here
//! are process- or thread-scoped counters: Linux hardware performance
-//! counters ([`HardwareCounter`]) and `getrusage` statistics
-//! ([`ResourceCounter`]). Nothing in this crate depends on GPUI, so any
+//! counters ([`HardwareCounter`]), `getrusage` statistics
+//! ([`ResourceCounter`]), and heap allocations counted by
+//! [`CountingAllocator`] ([`AllocationCounter`]). Nothing in this crate depends on GPUI, so any
//! Criterion benchmark can use it:
//!
//! ```ignore
@@ -992,6 +993,319 @@ impl Measurement for ResourceCounter {
}
}
+// ---------------------------------------------------------------------------
+// Heap allocations
+// ---------------------------------------------------------------------------
+
+/// A global allocator that forwards to `A` and counts what passes through it,
+/// for [`AllocationCounter`] and [`allocation_stats`].
+///
+/// Counting records no backtraces, so it adds a few relaxed atomic increments
+/// per allocation and is cheap enough to install in every benchmark binary.
+/// `A` can be any allocator, so a binary that wants to measure the allocator it
+/// ships with wraps that one:
+///
+/// ```ignore
+/// #[global_allocator]
+/// static ALLOCATOR: bench_metrics::CountingAllocator =
+/// bench_metrics::CountingAllocator::new(mimalloc::MiMalloc);
+/// ```
+///
+/// A binary has exactly one global allocator, so this can't be installed where a
+/// dependency already sets one (such as `ztracing` built with
+/// `ztracing_with_memory`); allocation metrics are then skipped.
+pub struct CountingAllocator {
+ inner: A,
+}
+
+impl CountingAllocator {
+ /// Wraps `inner`, which serves every allocation.
+ pub const fn new(inner: A) -> Self {
+ Self { inner }
+ }
+}
+
+// SAFETY: every method forwards to `inner` with the caller's arguments and
+// returns its result unchanged; counting never touches the memory.
+unsafe impl std::alloc::GlobalAlloc for CountingAllocator {
+ unsafe fn alloc(&self, layout: std::alloc::Layout) -> *mut u8 {
+ // SAFETY: the caller upholds `GlobalAlloc::alloc`'s contract.
+ let pointer = unsafe { self.inner.alloc(layout) };
+ if !pointer.is_null() {
+ allocation_counts::record_allocation(layout.size());
+ }
+ pointer
+ }
+
+ unsafe fn alloc_zeroed(&self, layout: std::alloc::Layout) -> *mut u8 {
+ // SAFETY: the caller upholds `GlobalAlloc::alloc_zeroed`'s contract.
+ let pointer = unsafe { self.inner.alloc_zeroed(layout) };
+ if !pointer.is_null() {
+ allocation_counts::record_allocation(layout.size());
+ }
+ pointer
+ }
+
+ unsafe fn dealloc(&self, pointer: *mut u8, layout: std::alloc::Layout) {
+ // SAFETY: the caller upholds `GlobalAlloc::dealloc`'s contract.
+ unsafe { self.inner.dealloc(pointer, layout) };
+ allocation_counts::record_free(layout.size());
+ }
+
+ unsafe fn realloc(
+ &self,
+ pointer: *mut u8,
+ layout: std::alloc::Layout,
+ new_size: usize,
+ ) -> *mut u8 {
+ // SAFETY: the caller upholds `GlobalAlloc::realloc`'s contract.
+ let new_pointer = unsafe { self.inner.realloc(pointer, layout, new_size) };
+ // A reallocation is counted as a new allocation replacing the old one,
+ // as dhat and heaptrack count it, so growing a `Vec` shows up as churn.
+ if !new_pointer.is_null() {
+ allocation_counts::record_free(layout.size());
+ allocation_counts::record_allocation(new_size);
+ }
+ new_pointer
+ }
+}
+
+/// Totals counted by [`CountingAllocator`] since the process started.
+#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
+pub struct AllocationStats {
+ /// Allocations served, including reallocations.
+ pub allocations: u64,
+ /// Bytes requested by those allocations.
+ pub allocated_bytes: u64,
+ /// Bytes returned by frees and by the old side of reallocations.
+ pub freed_bytes: u64,
+}
+
+impl AllocationStats {
+ /// Bytes allocated and not yet freed.
+ pub fn live_bytes(&self) -> i64 {
+ self.allocated_bytes as i64 - self.freed_bytes as i64
+ }
+}
+
+/// Returns the process's allocation totals, or `None` when this binary's
+/// global allocator is not a [`CountingAllocator`]. Differences between two
+/// calls give the allocations, bytes, and live-heap change of the code between
+/// them, across every thread.
+pub fn allocation_stats() -> Option {
+ allocation_counts::installed().then(allocation_counts::read)
+}
+
+/// Counters shared by every thread, plus each thread's own. Each thread
+/// increments one of several cache-line-aligned shards, so threads allocating
+/// concurrently rarely contend on a line; readers sum the shards. The
+/// per-thread counts are plain cells only their own thread reads.
+mod allocation_counts {
+ use super::AllocationStats;
+ use std::{
+ cell::Cell,
+ sync::atomic::{AtomicBool, AtomicU64, AtomicUsize, Ordering},
+ };
+
+ const SHARD_COUNT: usize = 32;
+
+ #[repr(align(128))]
+ struct Shard {
+ allocations: AtomicU64,
+ allocated_bytes: AtomicU64,
+ freed_bytes: AtomicU64,
+ }
+
+ static SHARDS: [Shard; SHARD_COUNT] = [const {
+ Shard {
+ allocations: AtomicU64::new(0),
+ allocated_bytes: AtomicU64::new(0),
+ freed_bytes: AtomicU64::new(0),
+ }
+ }; SHARD_COUNT];
+ static INSTALLED: AtomicBool = AtomicBool::new(false);
+ static NEXT_SHARD: AtomicUsize = AtomicUsize::new(0);
+
+ thread_local! {
+ // `const` and without `Drop`, so accessing these never allocates and
+ // still works while the thread's other thread-locals are being destroyed.
+ static SHARD_INDEX: Cell