refactor(multitude)!: unify local and shared chunks into one chunk type (#516)

- Collapse the two-chunk-type design into a single unified chunk,
simplifying the allocator code considerably and enabling O(1)
conversions of vectors and strings into arcs and boxes.

- Replace the dedicated `ArcUtf16Str`/`BoxUtf16Str` types with a
transparent `Utf16Str` newtype to get much better composaibility.

Co-authored-by: Martin Taillefer <mataille@microsoft.com>

Author: geeknoid

.spelling

@@ -45,7 +45,7 @@ fundle_macros = { path = "crates/fundle_macros", default-features = false, versi
 fundle_macros_impl = { path = "crates/fundle_macros_impl", default-features = false, version = "0.3.3" }
 http_extensions = { path = "crates/http_extensions", default-features = false, version = "0.6.2" }
 layered = { path = "crates/layered", default-features = false, version = "0.3.4" }
-multitude = { path = "crates/multitude", default-features = false, version = "0.3.2" }
+multitude = { path = "crates/multitude", default-features = false, version = "0.4.0" }
 ohno = { path = "crates/ohno", default-features = false, version = "0.3.6" }
 ohno_macros = { path = "crates/ohno_macros", default-features = false, version = "0.3.4" }
 recoverable = { path = "crates/recoverable", default-features = false, version = "0.1.6" }

Cargo.lock

@@ -3,7 +3,7 @@
 
 [package]
 name = "multitude"
-version = "0.3.2"
+version = "0.4.0"
 description = "Fast and flexible arena allocator."
 readme = "README.md"
 keywords = ["arena", "memory", "allocator", "bump"]

Cargo.toml

@@ -28,59 +28,54 @@ const SLICE_LEN: usize = 8;
 /// **and fully primed** so the timed region exercises only the warm
 /// bump cursor — no cold `refill_*` call on the first inner iteration.
 ///
-/// 1. `with_capacity_local(64 KiB) + with_capacity_shared(64 KiB)` pin
-///    the very first chunk for each flavor to the largest size class.
-///    The arena's adaptive `1 KiB → 64 KiB` ramp would otherwise call
-///    into the system allocator several times growing through the
-///    smaller classes during the timed region.
-/// 2. The arena's `current_local` / `current_shared` slots start in
-///    the empty-mutator state (lazy first-chunk install — see the
-///    design doc). A single throwaway allocation of each flavor pops
-///    the preallocated chunk from the provider cache and installs it
-///    in the `current_*` slot, so the timed region's very first
-///    allocation hits the warm bump path. This matches bumpalo's
-///    `warm_bump` (which similarly primes its cursor with a no-op
-///    alloc) and isolates the comparison to "in-chunk bump cost
-///    only" with no cold refill amortized into the per-op number.
+/// 1. `with_capacity(128 KiB)` pins the first chunks to the largest
+///    size class. The arena's adaptive `1 KiB → 64 KiB` ramp would
+///    otherwise call into the system allocator several times growing
+///    through the smaller classes during the timed region.
+/// 2. The arena's `current` slot starts in the empty-mutator state
+///    (lazy first-chunk install — see the design doc). A throwaway
+///    reference allocation and a throwaway `Arc` allocation pop the
+///    preallocated chunk(s) from the provider cache and install one in
+///    the `current` slot, so the timed region's very first allocation
+///    hits the warm bump path. This matches bumpalo's `warm_bump`
+///    (which similarly primes its cursor with a no-op alloc) and
+///    isolates the comparison to "in-chunk bump cost only" with no cold
+///    refill amortized into the per-op number.
 ///
-/// Only used by benches that exercise **both** flavors in the timed
-/// region: the `vec_builder` benches build a local `Vec` and then
-/// `into_arc()` it. Benches that touch a single flavor must use
-/// [`warm_arena_local`] / [`warm_arena_shared`] instead: priming the
-/// unused flavor allocates a dead-weight 64 KiB chunk that doubles the
-/// arena's memory footprint and inflates the measured per-op time
-/// through extra cache/TLB pressure at the batch working-set sizes
-/// criterion picks (verified: priming the unused shared chunk made
-/// `alloc_slice_copy` measure ~9x slower than its true cost).
+/// Only used by benches that allocate **both** references and smart
+/// pointers in the timed region: the `vec_builder` benches build a
+/// `Vec` and then `into_arc()` it. Benches that touch only one style
+/// must use [`warm_arena_local`] / [`warm_arena_shared`] instead:
+/// preallocating the extra 64 KiB doubles the arena's memory footprint
+/// and inflates the measured per-op time through extra cache/TLB
+/// pressure at the batch working-set sizes criterion picks (verified:
+/// the extra primed chunk made `alloc_slice_copy` measure ~9x slower
+/// than its true cost).
 fn warm_arena() -> Arena {
-    let arena = Arena::builder()
-        .with_capacity_local(64 * 1024)
-        .with_capacity_shared(64 * 1024)
-        .build();
+    let arena = Arena::builder().with_capacity(128 * 1024).build();
     let _: &mut u64 = arena.alloc(0_u64);
     let _ = arena.alloc_arc(0_u64);
     arena
 }
 
-/// Like [`warm_arena`] but primes **only** the local (ref/value)
-/// flavor. Used by benches whose timed region allocates exclusively
-/// from the local chunk (`alloc`, `alloc_str`, `alloc_slice_*` ref,
-/// `alloc_string*`). Priming the shared flavor here would add a
-/// dead-weight 64 KiB chunk — see [`warm_arena`].
+/// Like [`warm_arena`] but preallocates a single 64 KiB chunk and
+/// primes it with a reference allocation. Used by benches whose timed
+/// region allocates only references (`alloc`, `alloc_str`,
+/// `alloc_slice_*` ref, `alloc_string*`). Preallocating more would add
+/// a dead-weight 64 KiB chunk — see [`warm_arena`].
 fn warm_arena_local() -> Arena {
-    let arena = Arena::builder().with_capacity_local(64 * 1024).build();
+    let arena = Arena::builder().with_capacity(64 * 1024).build();
     let _: &mut u64 = arena.alloc(0_u64);
     arena
 }
 
-/// Like [`warm_arena`] but primes **only** the shared (`Box`/`Arc`)
-/// flavor. Used by benches whose timed region allocates exclusively
-/// from the shared chunk (every `*_box` / `*_arc` bench — both smart
-/// pointers are backed by refcounted shared chunks). Priming the local
-/// flavor here would add a dead-weight 64 KiB chunk — see
-/// [`warm_arena`].
+/// Like [`warm_arena`] but preallocates a single 64 KiB chunk and
+/// primes it with an `Arc` allocation. Used by benches whose timed
+/// region allocates only smart pointers (every `*_box` / `*_arc`
+/// bench). Preallocating more would add a dead-weight 64 KiB chunk —
+/// see [`warm_arena`].
 fn warm_arena_shared() -> Arena {
-    let arena = Arena::builder().with_capacity_shared(64 * 1024).build();
+    let arena = Arena::builder().with_capacity(64 * 1024).build();
     let _ = arena.alloc_arc(0_u64);
     arena
 }

crates/multitude/Cargo.toml

@@ -47,7 +47,7 @@ fn build_arena(arena: &Arena, payload: &[u8]) -> ArenaArc<[ArenaArc<[u8]>]> {
     for _ in 0..PROPERTIES {
         properties.push(arena.alloc_slice_copy_arc(payload));
     }
-    properties.try_into_arc().unwrap()
+    properties.try_into_arc_slice().unwrap()
 }
 
 fn build_arena_from_slice(arena: &Arena, properties: &[StdArc<[u8]>]) -> ArenaArc<[StdArc<[u8]>]> {

crates/multitude/README.md

@@ -53,23 +53,23 @@ fn bench_drop(c: &mut Criterion) {
     }
 
     drop_bench!("box_u64", {
-        let arena = Arena::builder().with_capacity_local(64 * 1024).build();
+        let arena = Arena::builder().with_capacity(64 * 1024).build();
         let mut h = Vec::with_capacity(N);
         for i in 0..N {
             h.push(arena.alloc_box(i as u64));
         }
         (h, arena)
     });
     drop_bench!("rc_u64", {
-        let arena = Arena::builder().with_capacity_local(64 * 1024).build();
+        let arena = Arena::builder().with_capacity(64 * 1024).build();
         let mut h = Vec::with_capacity(N);
         for i in 0..N {
             h.push(arena.alloc_arc(i as u64));
         }
         (h, arena)
     });
     drop_bench!("arc_u64", {
-        let arena = Arena::builder().with_capacity_local(64 * 1024).build();
+        let arena = Arena::builder().with_capacity(64 * 1024).build();
         let mut h = Vec::with_capacity(N);
         for i in 0..N {
             h.push(arena.alloc_arc(i as u64));
@@ -78,23 +78,23 @@ fn bench_drop(c: &mut Criterion) {
     });
 
     drop_bench!("box_droppy", {
-        let arena = Arena::builder().with_capacity_local(64 * 1024).build();
+        let arena = Arena::builder().with_capacity(64 * 1024).build();
         let mut h = Vec::with_capacity(N);
         for i in 0..N {
             h.push(arena.alloc_box(make_droppy(i)));
         }
         (h, arena)
     });
     drop_bench!("rc_droppy", {
-        let arena = Arena::builder().with_capacity_local(64 * 1024).build();
+        let arena = Arena::builder().with_capacity(64 * 1024).build();
         let mut h = Vec::with_capacity(N);
         for i in 0..N {
             h.push(arena.alloc_arc(make_droppy(i)));
         }
         (h, arena)
     });
     drop_bench!("arc_droppy", {
-        let arena = Arena::builder().with_capacity_local(64 * 1024).build();
+        let arena = Arena::builder().with_capacity(64 * 1024).build();
         let mut h = Vec::with_capacity(N);
         for i in 0..N {
             h.push(arena.alloc_arc(make_droppy(i)));
@@ -103,23 +103,23 @@ fn bench_drop(c: &mut Criterion) {
     });
 
     drop_bench!("str_box", {
-        let arena = Arena::builder().with_capacity_local(64 * 1024).build();
+        let arena = Arena::builder().with_capacity(64 * 1024).build();
         let mut h: Vec<Box<str>> = Vec::with_capacity(N);
         for i in 0..N {
             h.push(arena.alloc_str_box(format!("word{i}")));
         }
         (h, arena)
     });
     drop_bench!("str_rc", {
-        let arena = Arena::builder().with_capacity_local(64 * 1024).build();
+        let arena = Arena::builder().with_capacity(64 * 1024).build();
         let mut h: Vec<Arc<str>> = Vec::with_capacity(N);
         for i in 0..N {
             h.push(arena.alloc_str_arc(format!("word{i}")));
         }
         (h, arena)
     });
     drop_bench!("str_arc", {
-        let arena = Arena::builder().with_capacity_local(64 * 1024).build();
+        let arena = Arena::builder().with_capacity(64 * 1024).build();
         let mut h: Vec<Arc<str>> = Vec::with_capacity(N);
         for i in 0..N {
             h.push(arena.alloc_str_arc(format!("word{i}")));
@@ -128,23 +128,23 @@ fn bench_drop(c: &mut Criterion) {
     });
 
     drop_bench!("slice_box_u64", {
-        let arena = Arena::builder().with_capacity_local(64 * 1024).build();
+        let arena = Arena::builder().with_capacity(64 * 1024).build();
         let mut h: Vec<Box<[u64]>> = Vec::with_capacity(N);
         for _ in 0..N {
             h.push(arena.alloc_slice_fill_with_box::<u64, _>(SLICE_LEN, |j| j as u64));
         }
         (h, arena)
     });
     drop_bench!("slice_rc_u64", {
-        let arena = Arena::builder().with_capacity_local(64 * 1024).build();
+        let arena = Arena::builder().with_capacity(64 * 1024).build();
         let mut h: Vec<Arc<[u64]>> = Vec::with_capacity(N);
         for _ in 0..N {
             h.push(arena.alloc_slice_fill_with_arc::<u64, _>(SLICE_LEN, |j| j as u64));
         }
         (h, arena)
     });
     drop_bench!("slice_arc_u64", {
-        let arena = Arena::builder().with_capacity_local(64 * 1024).build();
+        let arena = Arena::builder().with_capacity(64 * 1024).build();
         let mut h: Vec<Arc<[u64]>> = Vec::with_capacity(N);
         for _ in 0..N {
             h.push(arena.alloc_slice_fill_with_arc::<u64, _>(SLICE_LEN, |j| j as u64));
@@ -153,23 +153,23 @@ fn bench_drop(c: &mut Criterion) {
     });
 
     drop_bench!("slice_box_droppy", {
-        let arena = Arena::builder().with_capacity_local(64 * 1024).build();
+        let arena = Arena::builder().with_capacity(64 * 1024).build();
         let mut h: Vec<Box<[DroppyT]>> = Vec::with_capacity(N);
         for _ in 0..N {
             h.push(arena.alloc_slice_fill_with_box::<DroppyT, _>(SLICE_LEN, make_droppy));
         }
         (h, arena)
     });
     drop_bench!("slice_rc_droppy", {
-        let arena = Arena::builder().with_capacity_local(64 * 1024).build();
+        let arena = Arena::builder().with_capacity(64 * 1024).build();
         let mut h: Vec<Arc<[DroppyT]>> = Vec::with_capacity(N);
         for _ in 0..N {
             h.push(arena.alloc_slice_fill_with_arc::<DroppyT, _>(SLICE_LEN, make_droppy));
         }
         (h, arena)
     });
     drop_bench!("slice_arc_droppy", {
-        let arena = Arena::builder().with_capacity_local(64 * 1024).build();
+        let arena = Arena::builder().with_capacity(64 * 1024).build();
         let mut h: Vec<Arc<[DroppyT]>> = Vec::with_capacity(N);
         for _ in 0..N {
             h.push(arena.alloc_slice_fill_with_arc::<DroppyT, _>(SLICE_LEN, make_droppy));
@@ -178,7 +178,7 @@ fn bench_drop(c: &mut Criterion) {
     });
 
     drop_bench!("alloc", {
-        let arena = Arena::builder().with_capacity_local(64 * 1024).build();
+        let arena = Arena::builder().with_capacity(64 * 1024).build();
         for i in 0..N {
             let _: &mut u64 = arena.alloc(i as u64);
         }

crates/multitude/benches/criterion_alloc.rs

@@ -61,22 +61,19 @@ fn warm_bump() -> bumpalo::Bump {
 }
 
 fn warm_arena() -> Arena {
-    // Warm: preallocate one chunk of the largest size class for each
-    // flavor AND prime the arena's current_local / current_shared
-    // mutators by performing a throwaway allocation of each flavor.
+    // Warm: preallocate chunks of the largest size class AND prime the
+    // arena's `current` mutator by performing a throwaway reference
+    // allocation and a throwaway `Arc` allocation.
     // The preallocated chunks live in the provider cache; the
-    // current_* slots start in the empty-mutator state and are only
+    // `current` slot starts in the empty-mutator state and is only
     // populated lazily on the first allocation. Without the prime,
-    // every bench fn entry would pay one cold `refill_*` (chunk-cache
+    // every bench fn entry would pay one cold `refill` (chunk-cache
     // pop + mutator install) on the first inner iteration, hiding
     // ~50 cold-path instructions inside the per-op instruction count
     // and adding cache-miss latency that doesn't reflect steady-state
     // performance. This mirrors bumpalo's `warm_bump` (which itself
     // primes its cursor with a no-op alloc).
-    let arena = Arena::builder()
-        .with_capacity_local(64 * 1024)
-        .with_capacity_shared(64 * 1024)
-        .build();
+    let arena = Arena::builder().with_capacity(128 * 1024).build();
     let _: &mut u64 = arena.alloc(0_u64);
     let _ = arena.alloc_arc(0_u64);
     arena

crates/multitude/benches/criterion_arc_array.rs

@@ -68,7 +68,7 @@ fn build_arena(arena: &Arena, payload: &[u8]) -> ArenaArrayOfArena {
     for _ in 0..PROPERTIES {
         properties.push(arena.alloc_slice_copy_arc(payload));
     }
-    properties.try_into_arc().unwrap()
+    properties.try_into_arc_slice().unwrap()
 }
 
 fn build_arena_from_slice(arena: &Arena, properties: &[StdArc<[u8]>]) -> ArenaArrayOfGlobal {
@@ -87,14 +87,11 @@ fn global_properties() -> Vec<StdArc<[u8]>> {
 }
 
 fn warm_arena() -> Arena {
-    // Warm: preallocate one chunk of the largest size class for each flavor
-    // AND prime the arena's current_local / current_shared mutators with a
-    // throwaway allocation, so the timed body never pays a cold `refill_*`.
-    // Mirrors `gungraun_alloc::warm_arena`.
-    let arena = Arena::builder()
-        .with_capacity_local(64 * 1024)
-        .with_capacity_shared(64 * 1024)
-        .build();
+    // Warm: preallocate chunks of the largest size class AND prime the
+    // arena's `current` mutator with a throwaway reference allocation
+    // and a throwaway `Arc` allocation, so the timed body never pays a
+    // cold `refill`. Mirrors `gungraun_alloc::warm_arena`.
+    let arena = Arena::builder().with_capacity(128 * 1024).build();
     let _: &mut u64 = arena.alloc(0_u64);
     let _ = arena.alloc_arc(0_u64);
     arena