Milestone Update v0.9.1

Author: James Gober

.github/workflows/ci.yml

@@ -94,7 +94,14 @@ jobs:
       - uses: actions/checkout@v5
       - uses: dtolnay/rust-toolchain@stable
       - uses: Swatinem/rust-cache@v2
-      - run: cargo doc --all-features --no-deps
+      # Both feature variants so we catch broken intra-doc links
+      # that resolve under one feature set but not another (e.g. a
+      # link to a `backtraces`-gated item from the always-on module
+      # rustdoc).
+      - name: Doc build (default features)
+        run: cargo doc --no-deps
+      - name: Doc build (all features)
+        run: cargo doc --all-features --no-deps
 
   msrv:
     name: MSRV (Rust 1.75)

CHANGELOG.md

@@ -7,6 +7,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.9.1] - 2026-05-14
+
 ### Added
 
 - **Tier 2: inline backtrace capture (`backtraces` feature).** Each
@@ -70,6 +72,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - CI workflow runs the `backtraces` test suite with
   `RUSTFLAGS="-C force-frame-pointers=yes"` so traces are
   meaningful on hosted runners.
+- **Walker reads are no longer `read_volatile`.** The walker reads
+  the current thread's own stack memory after the four
+  bounds/alignment/range/monotonicity checks; no other thread can
+  mutate that memory mid-walk. Plain reads let the compiler
+  schedule the loads and unblock register-allocation
+  opportunities. Same observable behaviour, with a small per-walk
+  speed-up.
+- **Table matching path no longer spins on `wait_published`.** The
+  init thread now uses `fetch_add` (instead of `store`) for the
+  bucket's `count` and `total_bytes` fields. Concurrent matching
+  writers can land their increments at any moment without being
+  clobbered, so the matching path becomes two `fetch_add` calls
+  with no spin loop. Readers (`call_sites_report`) still gate on
+  `frame_count > 0` for sample-frame coherence.
+- CI: ASAN job sets `ASAN_OPTIONS=detect_stack_use_after_return=0`
+  so the stack-bounds test runs against the real stack rather
+  than ASAN's fake-stack heap allocation. The walker is
+  unaffected either way; the test just needed a real-stack
+  context to assert against.
+- CI: added a defensive "Verify toolchain is fully installed"
+  step after `dtolnay/rust-toolchain@stable` to heal the
+  occasional macOS runner-image case where `cargo` resolves to
+  `rustup-init`.
 
 ### Design notes
 
@@ -201,6 +226,7 @@ will not work. Real implementation lands in `0.9.x` along with:
 - DHAT-compatible JSON output.
 - Statistical validation suite.
 
-[Unreleased]: https://github.com/jamesgober/mod-alloc/compare/v0.9.0...HEAD
+[Unreleased]: https://github.com/jamesgober/mod-alloc/compare/v0.9.1...HEAD
+[0.9.1]: https://github.com/jamesgober/mod-alloc/compare/v0.9.0...v0.9.1
 [0.9.0]: https://github.com/jamesgober/mod-alloc/compare/v0.1.0...v0.9.0
 [0.1.0]: https://github.com/jamesgober/mod-alloc/releases/tag/v0.1.0

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "mod-alloc"
-version = "0.9.0"
+version = "0.9.1"
 edition = "2021"
 rust-version = "1.75"
 readme = "README.md"

Cargo.toml

@@ -23,20 +23,20 @@
 
 ## What it does
 
-`mod-alloc` is a global-allocator wrapper that tracks every
-allocation and deallocation. It answers:
+`mod-alloc` is a `#[global_allocator]` wrapper that tracks every
+allocation and answers four questions for the code that runs while
+it is installed:
 
 - **How many allocations did this code path make?**
-- **How many total bytes were allocated?**
+- **How many total bytes did it allocate?**
 - **What was the peak resident memory?**
-- **Which call-sites caused the most allocations?** (with `backtraces` feature)
+- **Which call sites did most of the allocating?** (with the
+  `backtraces` feature)
 
-Designed as a lean replacement for `dhat` with:
-
-- **MSRV 1.75** (vs dhat's 1.85+)
-- **Zero external dependencies** in the hot path (no `backtrace` crate)
-- **Lower overhead** per allocation via purpose-built inline capture
-- **DHAT-compatible output** so existing viewer tools work (via the `dhat-compat` feature)
+The whole crate is `std`-only. No `backtrace`, no `addr2line`, no
+`gimli`, no `libc`. Inline frame-pointer walking on `x86_64` and
+`aarch64` for call-site capture; raw `mmap` / `VirtualAlloc` for
+the per-thread arena and the global aggregation table.
 
 ## Quick start
 
@@ -49,7 +49,7 @@ static GLOBAL: ModAlloc = ModAlloc::new();
 fn main() {
     let p = Profiler::start();
 
-    let v: Vec<u64> = (0..1000).collect();
+    let v: Vec<u64> = (0..1_000).collect();
     drop(v);
 
     let stats = p.stop();
@@ -63,36 +63,98 @@ fn main() {
 
 ```toml
 [dependencies]
-mod-alloc = "0.9"                                                      # counters only (default)
-mod-alloc = { version = "0.9", features = ["backtraces"] }             # + call-site capture (lands in v0.9.1)
-mod-alloc = { version = "0.9", features = ["dhat-compat"] }            # + DHAT-format output (lands in v0.9.3)
+mod-alloc = "0.9"                                            # Tier 1: counters (default)
+mod-alloc = { version = "0.9", features = ["backtraces"] }   # Tier 2: call-site capture
+mod-alloc = { version = "0.9", features = ["dhat-compat"] }  # Tier 3: DHAT JSON output (v0.9.3)
+```
+
+| Feature       | What it adds                                            | Status |
+|---------------|---------------------------------------------------------|--------|
+| `counters`    | Four lock-free counters via `GlobalAlloc` (default)     | shipped (v0.9.0) |
+| `backtraces`  | Inline FP walk + per-call-site aggregation              | shipped (v0.9.1) |
+| `dhat-compat` | Emit JSON for the official DHAT viewer                  | planned (v0.9.3) |
+
+## Backtraces
+
+Enabling the `backtraces` feature requires frame pointers in the
+caller's build:
+
+```toml
+# .cargo/config.toml
+[build]
+rustflags = ["-C", "force-frame-pointers=yes"]
+```
+
+The crate's `build.rs` emits a `cargo:warning=` at compile time if
+`RUSTFLAGS` is missing this. Without it the walker degrades
+gracefully (returns shallow or empty traces) but does not crash.
+
+The aggregation-table size is configurable at process start:
+
+```bash
+MOD_ALLOC_BUCKETS=16384 ./your-binary
 ```
 
+Default is 4,096 buckets (~384 KB). Range `[64, 1_048_576]`,
+rounded up to the next power of two.
+
+## Performance
+
+Measured per allocation, end to end, on a Windows x86_64 dev host
+with `cargo run --release --example bench_overhead`:
+
+| Build                                  | Per alloc + dealloc cycle |
+|----------------------------------------|--------------------------:|
+| Tier 1 only (`counters`, default)      |        **34.9 ns**        |
+| Tier 1 + Tier 2 (`backtraces`)         |       **~1,950 ns**       |
+
+Tier 1 comes in well under the 50 ns target from the spec
+([`REPS.md`](REPS.md) section 6). Tier 2 is currently above the
+200 ns target in that section; closing that gap is tracked for
+v0.9.1.1. The Tier 2 path is correct and recursion-safe in the
+current release; the optimisation is a separate, focused pass.
+
 ## Why a new allocation profiler
 
-`dhat` is the de-facto standard but its dependency chain
-(`backtrace` 0.3.76 → `addr2line` 0.25.1) locks consumers at Rust
-1.85. For projects with broader MSRV targets, this is a real cost.
+`dhat` is the de facto standard for allocation profiling in Rust,
+but its dependency chain (`backtrace 0.3.76` → `addr2line 0.25.1`)
+forces consumers to MSRV `1.85`+. For projects with a broader MSRV
+target, that cost is real.
 
-`mod-alloc` provides the same core capability with inline backtrace
-capture (frame-pointer-based, x86_64 + aarch64 initially) and no
-external dependencies. The trade: fewer architectures supported in
-v1.0; we add ARM32, RISC-V, etc. based on demand.
+`mod-alloc` provides the same core capability with inline
+backtrace capture (frame-pointer-based, `x86_64` + `aarch64`) and
+no external dependencies. The trade-off is fewer architectures
+supported in `1.0`; ARM32, RISC-V, and others land based on
+demand.
 
 ## Status
 
-`v0.9.0` ships Tier 1 (counters). Installing `ModAlloc` as
-`#[global_allocator]` tracks every allocation, deallocation,
-reallocation, and zero-init allocation against four lock-free
-atomic counters. Per-allocation overhead measures under 50 ns on
-x86_64 (`cargo run --release --example bench_overhead`). Tier 2
-(inline backtrace capture) lands in `v0.9.1`. Tier 3
-(DHAT-compatible JSON output) lands in `v0.9.3`. The `1.0` release
-freezes the public API and the wire format.
+| Milestone                                  | Version  | State    |
+|--------------------------------------------|----------|----------|
+| Name-claim placeholder                     | `v0.1.0` | shipped  |
+| Real `GlobalAlloc` + Tier 1 counters       | `v0.9.0` | shipped  |
+| Tier 2: inline backtrace capture           | `v0.9.1` | shipped  |
+| Tier 2 perf optimisation                   | `v0.9.1.1` | planned |
+| Symbolication for reports                  | `v0.9.2` | planned  |
+| Tier 3: DHAT-compatible JSON output        | `v0.9.3` | planned  |
+| `dev-bench` integration (drop dhat)        | `v0.9.4` | planned  |
+| Stable API (`1.0`)                         | `v1.0.0` | planned  |
+
+The `1.0` release freezes the public API and the wire format.
+Breaking changes after that require a major bump.
+
+## Out of scope
+
+- Replacing the system allocator. Use `mimalloc` or
+  `jemallocator` for that.
+- Use-after-free / double-free detection. Use AddressSanitizer.
+- Source-level instrumentation (build.rs, proc macros). The one
+  build.rs in this crate exists solely to detect missing frame
+  pointers at compile time.
 
 ## Minimum supported Rust version
 
-`1.75`, pinned in `Cargo.toml` and verified by CI.
+`1.75`, pinned in `Cargo.toml` and verified by CI on every push.
 
 ## License
 
@@ -106,4 +168,4 @@ Apache-2.0. See [LICENSE](LICENSE).
   <br>
   <h2></h2>
   Copyright &copy; 2026 James Gober.
-</div>
+</div>

README.md

@@ -151,23 +151,28 @@ pub(crate) fn record(frames: &Frames, size: u64) {
                 .compare_exchange(0, h, Ordering::Release, Ordering::Acquire)
             {
                 Ok(_) => {
-                    // We own the initialisation phase. Write
-                    // `sample_frames` first, then the counts,
-                    // then publish via `frame_count` with Release.
+                    // We own the initialisation phase. Use
+                    // `fetch_add` (not `store`) on `count` and
+                    // `total_bytes` so concurrent matching
+                    // writers never have their increments
+                    // clobbered by our initial value. This lets
+                    // the matching path skip `wait_published`
+                    // entirely.
                     for i in 0..count {
                         bucket.sample_frames[i].store(frames.frames[i], Ordering::Relaxed);
                     }
-                    bucket.count.store(1, Ordering::Relaxed);
-                    bucket.total_bytes.store(size, Ordering::Relaxed);
+                    bucket.count.fetch_add(1, Ordering::Relaxed);
+                    bucket.total_bytes.fetch_add(size, Ordering::Relaxed);
                     bucket.frame_count.store(count as u64, Ordering::Release);
                     return;
                 }
                 Err(observed) => {
                     if observed == h {
                         // Same call site, another writer claimed
-                        // first. Wait for them to publish, then
-                        // increment.
-                        wait_published(bucket);
+                        // first. The init thread now uses
+                        // `fetch_add` (not `store`), so our
+                        // increment cannot be clobbered even if
+                        // it lands before init finishes.
                         bucket.count.fetch_add(1, Ordering::Relaxed);
                         bucket.total_bytes.fetch_add(size, Ordering::Relaxed);
                         return;
@@ -177,7 +182,11 @@ pub(crate) fn record(frames: &Frames, size: u64) {
                 }
             }
         } else if existing == h {
-            wait_published(bucket);
+            // Hot path: same site already in this bucket. No
+            // wait_published needed because the init thread now
+            // uses fetch_add for count/total_bytes; whether init
+            // has finished publishing `sample_frames` is a
+            // reader (`call_sites_report`) concern, not ours.
             bucket.count.fetch_add(1, Ordering::Relaxed);
             bucket.total_bytes.fetch_add(size, Ordering::Relaxed);
             return;
@@ -191,12 +200,6 @@ pub(crate) fn record(frames: &Frames, size: u64) {
     }
 }
 
-fn wait_published(bucket: &Bucket) {
-    while bucket.frame_count.load(Ordering::Acquire) == 0 {
-        core::hint::spin_loop();
-    }
-}
-
 /// Drain the per-call-site table into a `Vec<CallSiteStats>`.
 ///
 /// Flushes the calling thread's arena first so recent events

src/backtrace/table.rs

@@ -71,8 +71,15 @@ pub(crate) fn walk(initial_fp: u64, bounds: StackBounds) -> Frames {
         // produce a `u64` value treated as bits; we do not
         // dereference them further as pointers without the same
         // checks repeated on the next iteration.
-        let new_fp = unsafe { core::ptr::read_volatile(fp as *const u64) };
-        let return_addr = unsafe { core::ptr::read_volatile((fp + 8) as *const u64) };
+        //
+        // Plain reads (not `read_volatile`): the memory we are
+        // reading is on the calling thread's own stack; no other
+        // thread mutates it during the walk, so the compiler is
+        // free to schedule these reads however it likes. The
+        // `read_volatile` we used previously cost ~50-100 ns per
+        // walk for no safety benefit.
+        let new_fp = unsafe { *(fp as *const u64) };
+        let return_addr = unsafe { *((fp + 8) as *const u64) };
 
         // Monotonicity: chain must progress upward (older frames
         // sit at higher addresses on stacks that grow down).