Milestone Update v0.9.1

Author: James Gober

.cargo/config.toml

@@ -0,0 +1,14 @@
+# Build configuration for the `mod-alloc` crate itself.
+#
+# Enables frame pointers for in-crate builds so the `backtraces`
+# feature's inline FP walker can capture real frames during the
+# crate's own test suite and examples. This file does NOT affect
+# downstream consumers; cargo only honours `.cargo/config.toml`
+# inside the crate root being built from.
+#
+# Downstream callers who want backtrace capture must enable frame
+# pointers in their OWN build (the `backtraces` feature's build.rs
+# emits a warning if they have not).
+
+[build]
+rustflags = ["-C", "force-frame-pointers=yes"]

.github/workflows/ci.yml

@@ -30,9 +30,22 @@ jobs:
       - name: Build (no default features)
         run: cargo build --no-default-features --verbose
 
+      - name: Build (backtraces feature)
+        env:
+          RUSTFLAGS: "-C force-frame-pointers=yes"
+        run: cargo build --features backtraces --verbose
+      - name: Test (backtraces feature)
+        env:
+          RUSTFLAGS: "-C force-frame-pointers=yes"
+        run: cargo test --features backtraces --verbose
+
       - name: Build (all features)
+        env:
+          RUSTFLAGS: "-C force-frame-pointers=yes"
         run: cargo build --all-features --verbose
       - name: Test (all features)
+        env:
+          RUSTFLAGS: "-C force-frame-pointers=yes"
         run: cargo test --all-features --verbose
 
   clippy:
@@ -73,8 +86,30 @@ jobs:
   msrv:
     name: MSRV (Rust 1.75)
     runs-on: ubuntu-latest
+    env:
+      RUSTFLAGS: "-C force-frame-pointers=yes"
     steps:
       - uses: actions/checkout@v5
       - uses: dtolnay/rust-toolchain@1.75
       - uses: Swatinem/rust-cache@v2
-      - run: cargo build --all-features --verbose
+      - run: cargo build --all-features --verbose
+
+  asan:
+    name: AddressSanitizer (nightly Linux)
+    runs-on: ubuntu-latest
+    env:
+      # ASAN insurance for the unsafe backtrace path. Catches
+      # out-of-bounds reads in the FP walker that pass the
+      # mandatory range checks but would still be observable to
+      # ASAN. Nightly is required because -Zsanitizer is unstable.
+      RUSTFLAGS: "-Zsanitizer=address -C force-frame-pointers=yes"
+      RUSTDOCFLAGS: "-Zsanitizer=address"
+    steps:
+      - uses: actions/checkout@v5
+      - uses: dtolnay/rust-toolchain@nightly
+        with:
+          components: rust-src
+      - uses: Swatinem/rust-cache@v2
+      - name: Test under ASAN
+        run: |
+          cargo test --features backtraces --target x86_64-unknown-linux-gnu -Zbuild-std --verbose

CHANGELOG.md

@@ -7,6 +7,103 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- **Tier 2: inline backtrace capture (`backtraces` feature).** Each
+  tracked allocation, zero-init allocation, and reallocation
+  captures up to 8 frames of its call site via inline
+  frame-pointer walking. Available on `x86_64` and `aarch64`.
+  Other architectures compile but capture is a no-op.
+- **`ModAlloc::call_sites()`** drains the per-call-site
+  aggregation table into a `Vec<CallSiteStats>`. Each row carries
+  raw return addresses (top of stack first), the number of
+  allocations attributed to the site, and the total bytes.
+  Symbolication ships in v0.9.2.
+- **`CallSiteStats`** public type behind the `backtraces` feature.
+- **Per-thread arena** (64 KB OS-page region per thread, 512
+  events per flush) and **global aggregation table** (4,096
+  buckets by default, ~384 KB) allocated through raw
+  `mmap` / `VirtualAlloc` so the backtrace path never recurses
+  into `ModAlloc::alloc` for its own state.
+- **`MOD_ALLOC_BUCKETS` env var** to override the
+  aggregation-table size at process start. Value is rounded up to
+  the next power of two and clamped to `[64, 1_048_576]`.
+- **`build.rs`** (one-off approved exception): warns at compile
+  time when `RUSTFLAGS` is missing `-C force-frame-pointers=yes`
+  and the `backtraces` feature is on. See
+  `.dev/DIRECTIVES.md` section 2.1 for the documented exception.
+- **`.cargo/config.toml`** in the crate root enables frame
+  pointers for the crate's own builds so the test suite and
+  examples produce useful traces. Downstream consumers must
+  enable the flag in their own builds.
+- New tests:
+  - `tests/backtrace_real_chain.rs`: captures from a deeply
+    nested `#[inline(never)]` call chain.
+  - `tests/backtrace_fuzz.rs`: SplitMix64-driven random workload
+    proving the walker is total under varied allocation patterns
+    (10,000 iterations).
+  - `tests/backtrace_concurrent.rs`: 32-thread aggregation
+    stress test.
+  - `src/backtrace/*` unit tests cover hash determinism, walker
+    safety checks (null, alignment, out-of-range, non-monotonic,
+    max-frame cap), arena round-trip, table claim races, and
+    stack-bounds discovery.
+- **`examples/backtraces.rs`** demonstrates installing
+  `ModAlloc`, exercising a few distinct call paths, and printing
+  the top sites by total bytes.
+- **CI: AddressSanitizer nightly job.** A dedicated job in
+  `.github/workflows/ci.yml` runs the test suite under
+  `-Zsanitizer=address` on Linux x86_64 to catch any UB in the
+  unsafe FP-walker path that survives the in-walker safety
+  checks.
+
+### Changed
+
+- `GlobalAlloc::alloc`, `alloc_zeroed`, and `realloc` invoke
+  `backtrace::record_event` after the existing counter update
+  when the `backtraces` feature is on. `dealloc` does not capture
+  (matches dhat: call sites describe who allocated, not who
+  freed).
+- Per maintainer guidance, realloc captures all events including
+  shrinks, matching dhat's per-event accounting. Documented in
+  the rustdoc.
+- CI workflow runs the `backtraces` test suite with
+  `RUSTFLAGS="-C force-frame-pointers=yes"` so traces are
+  meaningful on hosted runners.
+
+### Design notes
+
+- **Reentrancy on the backtrace path.** The walker reads memory
+  inside the cached stack bounds (which are queried via
+  `GetCurrentThreadStackLimits` on Windows,
+  `pthread_getattr_np` on Linux, `pthread_get_stackaddr_np` on
+  Darwin / BSD). All reads are pointer-aligned and in-range; no
+  page faults are possible. The existing `IN_ALLOC` reentrancy
+  guard from v0.9.0 catches any pathological allocation
+  triggered transitively from inside the backtrace path (e.g.
+  libc lazy-init during the first `pthread_getattr_np`).
+- **No `HashMap` in the hot path.** The global aggregation table
+  is a fixed-size open-addressed array allocated once via raw OS
+  pages, with atomic per-bucket CAS for claim and linear probing
+  for index collisions. Hash collisions on the 64-bit FxHash are
+  a documented limitation (different sites with identical hashes
+  get conflated).
+- **Bucket publish protocol.** Each bucket uses a two-phase
+  claim: CAS on `hash` first (Release), then write
+  `sample_frames`, then store `frame_count` with Release. Readers
+  gate on `frame_count > 0` after observing a non-zero hash;
+  this prevents torn reads of the sample frames.
+
+### Migration
+
+The default build (Tier 1 only) is unchanged. Existing callers
+need no edits.
+
+Users opting in to the `backtraces` feature must add
+`-C force-frame-pointers=yes` to their build configuration. The
+included `build.rs` emits a `cargo:warning=` at compile time if
+this is missing.
+
 ## [0.9.0] - 2026-05-13
 
 ### Added

Cargo.toml

@@ -5,6 +5,7 @@ edition = "2021"
 rust-version = "1.75"
 readme = "README.md"
 license = "Apache-2.0"
+build = "build.rs"
 
 authors = [
     "James Gober <me@jamesgober.com>"

build.rs

@@ -0,0 +1,45 @@
+//! mod-alloc build script.
+//!
+//! Approved exception per `.dev/DIRECTIVES.md` section 2.1. The
+//! crate does not generally use `build.rs`. This script exists
+//! solely to detect whether the user's toolchain has frame
+//! pointers enabled when the `backtraces` feature is on, and to
+//! emit a `cargo:warning=` directive if not.
+//!
+//! Frame pointers are a prerequisite for the inline FP walker
+//! shipped in `v0.9.1`. Without them the walker returns empty or
+//! shallow traces on release builds; a build-time hint saves
+//! users from debugging that downstream.
+//!
+//! This script never fails the build. The walker degrades
+//! gracefully at runtime if FP support is absent.
+
+use std::env;
+
+fn main() {
+    println!("cargo:rerun-if-env-changed=RUSTFLAGS");
+    println!("cargo:rerun-if-env-changed=CARGO_ENCODED_RUSTFLAGS");
+
+    let backtraces_on = env::var_os("CARGO_FEATURE_BACKTRACES").is_some();
+    if !backtraces_on {
+        return;
+    }
+
+    let rustflags = env::var("CARGO_ENCODED_RUSTFLAGS")
+        .or_else(|_| env::var("RUSTFLAGS"))
+        .unwrap_or_default();
+
+    let has_fp = rustflags.contains("force-frame-pointers=yes")
+        || rustflags.contains("force-frame-pointers=y")
+        || rustflags.contains("force-frame-pointers=on");
+
+    if !has_fp {
+        println!(
+            "cargo:warning=mod-alloc: the `backtraces` feature is enabled but \
+             RUSTFLAGS does not include `-C force-frame-pointers=yes`. The inline \
+             FP walker requires frame pointers; without them traces will be empty \
+             or shallow on release builds. Add to .cargo/config.toml: [build] \
+             rustflags = [\"-C\", \"force-frame-pointers=yes\"]"
+        );
+    }
+}

examples/backtraces.rs

@@ -0,0 +1,82 @@
+//! Per-call-site report demo.
+//!
+//! Run with:
+//!   cargo run --release --features backtraces --example backtraces
+//!
+//! Requires frame pointers for useful output. The in-crate
+//! `.cargo/config.toml` enables `-C force-frame-pointers=yes` for
+//! this crate's own builds; downstream users opting into the
+//! `backtraces` feature must enable the flag in their own build.
+
+#[cfg(feature = "backtraces")]
+#[global_allocator]
+static GLOBAL: mod_alloc::ModAlloc = mod_alloc::ModAlloc::new();
+
+#[cfg(feature = "backtraces")]
+#[inline(never)]
+fn alloc_small() {
+    let v: Vec<u8> = Vec::with_capacity(64);
+    std::hint::black_box(&v);
+}
+
+#[cfg(feature = "backtraces")]
+#[inline(never)]
+fn alloc_medium() {
+    let v: Vec<u8> = Vec::with_capacity(1024);
+    std::hint::black_box(&v);
+}
+
+#[cfg(feature = "backtraces")]
+#[inline(never)]
+fn alloc_large() {
+    let v: Vec<u8> = Vec::with_capacity(64 * 1024);
+    std::hint::black_box(&v);
+}
+
+#[cfg(feature = "backtraces")]
+fn main() {
+    for _ in 0..1_000 {
+        alloc_small();
+    }
+    for _ in 0..100 {
+        alloc_medium();
+    }
+    for _ in 0..10 {
+        alloc_large();
+    }
+
+    let snap = GLOBAL.snapshot();
+    println!("Process-wide snapshot:");
+    println!("  alloc_count:   {}", snap.alloc_count);
+    println!("  total_bytes:   {}", snap.total_bytes);
+    println!("  current_bytes: {}", snap.current_bytes);
+    println!("  peak_bytes:    {}", snap.peak_bytes);
+    println!();
+
+    let mut sites = GLOBAL.call_sites();
+    sites.sort_by_key(|s| std::cmp::Reverse(s.total_bytes));
+
+    println!("Top 10 call sites by total bytes:");
+    println!(
+        "{:>10}  {:>14}  {:>4}  {:>18}",
+        "count", "total_bytes", "frm", "top frame"
+    );
+    for (rank, site) in sites.iter().take(10).enumerate() {
+        println!(
+            "{rank:>2}: {count:>6}  {bytes:>14}  {frm:>4}  {top:#018x}",
+            rank = rank,
+            count = site.count,
+            bytes = site.total_bytes,
+            frm = site.frame_count,
+            top = site.frames[0],
+        );
+    }
+}
+
+#[cfg(not(feature = "backtraces"))]
+fn main() {
+    eprintln!(
+        "this example requires the `backtraces` feature; run with \
+         `cargo run --features backtraces --example backtraces`"
+    );
+}