Multitude

Fast and flexible arena-based bump allocator.

multitude is an arena-based bump allocator designed to improve the performance of applications that have phase-oriented logic, which is when groups of related allocations live and die together. Service request handling and parsers are two examples of this pattern which usually benefit from a bump allocator.

multitude works by accumulating large chunks of memory allocated from the system and then carving out smaller pieces of it for application use using a fast bump allocation strategy, which is considerably faster than allocating from the system. The downside however is that the individual allocations can’t be freed separately. Instead, memory is reclaimed and returned to the system in bulk when the entire arena is dropped.

Why Another Bump Allocator?

The Rust ecosystem has a few bump allocators, the most popular being bumpalo. multitude uses a different implementation strategy and has a richer API surface making it suitable for more use cases. The main features that set multitude apart are:

1. Flexibility. multitude provides multiple allocation styles, all of which can coexist in the same arena:

   • Mutable references with lifetimes tied to the arena (&mut T, &mut str, &mut [T]).
   • Reference-counted smart pointers (Rc, RcStr) for single-threaded sharing.
   • Atomic reference-counted smart pointers (Arc, ArcStr) for cross-thread sharing.
   • Owned, mutable smart pointers (Box, BoxStr).

2. Early Reclamation. In many situations, multitude can reclaim memory from individual chunks as soon as their reference counts drop to zero, without waiting for the entire arena to be dropped. This allows for more efficient memory usage in long-running arenas with many short-lived allocations.

3. Smart Pointers Can Outlive the Arena. The reference-counted smart pointers produced by multitude can keep their owning chunk alive even after the arena itself has been dropped, allowing for more flexible memory management and longer-lived data structures.

4. Drop Support. multitude automatically runs Drop for allocated values at the appropriate time.

5. Efficient Immutable String References. multitude provides RcStr, ArcStr, and BoxStr — single-pointer (8 bytes) smart pointers to UTF-8 strings stored in the arena. Refcounted, atomic-refcounted, and owned-mutable variants respectively, all sharing the same compact layout.

6. Efficient Mutable Strings and Vectors. multitude provides String and Vec which are growable collections that live in the arena and can be frozen into compact reference-counted smart pointers when you’re done building.

7. Dynamically-Sized Types. multitude supports dynamically-sized types (DSTs) like slices and strings, allowing you to allocate and manage them in the arena with the same flexibility as sized types. The dst-factory crate is a great companion for building DSTs in the arena.

8. format!-style Macro. multitude includes a format!-style macro that allows you to create formatted strings directly in the arena, avoiding intermediate allocations and copies.

9. UTF-16 Support. With the utf16 Cargo feature, multitude provides a parallel set of arena-resident UTF-16 string types (RcUtf16Str, ArcUtf16Str, BoxUtf16Str, Utf16String) and a format_utf16! macro for FFI / Windows / JS-engine interop without per-call transcoding at every boundary.

10. #![no_std] Support. multitude can be used in #![no_std] environments, making it suitable for embedded systems and other resource-constrained contexts.

Example

use multitude::Arena;

let arena = Arena::new();

// Cheap reference-counted allocation of any user type.
struct Point { x: f64, y: f64 }
let p = arena.alloc_rc(Point { x: 3.0, y: 4.0 });
let p2 = p.clone();
assert_eq!(p.x, p2.x);

// Single-pointer immutable strings.
let name = arena.alloc_str_rc("Alice");
assert_eq!(&*name, "Alice");

// format! macro returning a String (call .into_arena_str() to
// freeze into a compact 8-byte RcStr).
let greeting = multitude::strings::format!(in &arena, "Hello, {}!", "world");
assert_eq!(&*greeting, "Hello, world!");

Flexibility

multitude supports a variety of ways to allocate data and track it over time.

Simple References

The simplest use of the arena is to get plain mutable references. The lifetime of those references is then tied to the arena’s own lifetime.

let arena = multitude::Arena::new();
let x: &mut u32 = arena.alloc(42);
let y: &mut u32 = arena.alloc(100);
*x += 1;
*y += 1;
assert_eq!(*x, 43);
assert_eq!(*y, 101);

// Strings and slices too:
let s: &mut str = arena.alloc_str("hello");
let v: &mut [i32] = arena.alloc_slice_copy(&[1, 2, 3]);

These references can’t outlive the arena, which limits their use. But they are the fastest and most efficient way to allocate from the arena, so if the lifetime constraints are tolerable, simple references are the way to go.

Smart Pointers

Smart pointers (Rc, Arc, Box and their str variations) work in a way similar to the like-named types in the standard library, except that they reference addresses within an arena.

use multitude::Rc;

struct Point {
    x: f64,
    y: f64,
}

let p: Rc<Point> = {
    let arena = multitude::Arena::new();
    arena.alloc_rc(Point { x: 3.0, y: 4.0 })
    // arena dropped here
};
assert_eq!(p.x, 3.0);

Although Arena itself is single-threaded (!Send and !Sync), the arc-family of types (e.g., Arc) enable cross-thread sharing.

let arena = multitude::Arena::new();
let shared = arena.alloc_arc(42_u64);
let h = std::thread::spawn(move || *shared);
assert_eq!(42, h.join().unwrap());

Box is a unique owner whose Drop runs T::drop immediately when the smart pointer is dropped and provides &mut T access, similar to alloc::boxed::Box but backed by the arena.

let arena = multitude::Arena::new();
let mut v = arena.alloc_box(vec![1, 2, 3]);
v.push(4);
assert_eq!(*v, vec![1, 2, 3, 4]);
drop(v); // The vec drop runs here, freeing its heap buffer.

Collections

Vec and String are growable collections that live in the arena.

Additionally, you can use an arena as the allocator for any type from the allocator-api2 ecosystem (including hashbrown::HashMap).

use multitude::Arena;
use multitude::vec::{CollectIn, Vec};

let arena = Arena::new();

let mut v = arena.alloc_vec::<i32>();
for i in 0..5 {
    v.push(i);
}

// CollectIn trait for iterator collection.
let squares: Vec<i32, _> = (1..=5).map(|i| i * i).collect_in(&arena);
assert_eq!(squares.as_slice(), &[1, 4, 9, 16, 25]);

Freezing

String and Vec are designed as transient builders. They carry a data pointer + length + capacity + arena reference.

Once you’re done building, you can freeze them into immutable smart pointers:

• String::into_arena_str → RcStr (8 bytes). The freeze itself is O(1) — no copy, no new allocation.
• Vec::into_arena_rc → Rc<[T]> (16-byte slice fat pointer; immutable, cloneable, refcount-based). For T: !Drop, the freeze is O(1) too.

Both freezes also reclaim any unused capacity left in the buffer when the conditions allow it, so those bytes become available for the next allocation.

use multitude::Arena;
use multitude::strings::RcStr;

let arena = Arena::new();

// Build phase: 32-byte builder, alive briefly.
let mut builder = arena.alloc_string();
builder.push_str("hello, ");
builder.push_str("world");

// Freeze for storage: 8-byte single-pointer smart pointer. O(1) — no copy.
let stored: RcStr = builder.into_arena_str();
assert_eq!(&*stored, "hello, world");

Use this pattern whenever you’d be storing many strings or slices long-term — the per-pointer savings (16 bytes for strings, 8 for slices) add up quickly across millions of items, and the frozen smart pointers are also cheaper to clone.

See BUMPALO.md for a feature-by-feature comparison with bumpalo.

Strings

multitude provides a family of arena-resident string types in the strings module. The model is the same one used for arbitrary values elsewhere in the crate — bump-allocation backed by a per-chunk refcount — but specialized for UTF-8 / UTF-16 text and a compact single-pointer representation.

There are two roles a string type can play:

1. Smart pointers (immutable / owned). Compact handles to string data already stored in the arena. They use a single-pointer (8 bytes on 64-bit) layout — half the size of &str — by storing the length inline with the string bytes. They differ in how sharing and mutability work:

   UTF-8	UTF-16	Sharing	Mutable	Notes
   RcStr	RcUtf16Str	refcount, !Send/!Sync	no	cheapest clone
   ArcStr	ArcUtf16Str	atomic refcount, Send + Sync	no	cross-thread
   BoxStr	BoxUtf16Str	unique owner	yes	drops eagerly

   Like the other arena smart pointers, they keep their owning chunk alive via a refcount, so they can outlive the Arena they came from.

2. Builders (mutable, growable). String and Utf16String are transient growable buffers — small structs (32 bytes) carrying a data pointer + length + capacity + arena reference. You build them up with push_str / push_char / format! / format_utf16!, then freeze them in O(1) into one of the smart pointers above:

   Builder	Freeze method	Result
   String	into_arena_str	RcStr
   Utf16String	into_arena_utf16_str	RcUtf16Str

   The freeze reuses the buffer in place — no copy — and returns any unused tail capacity to the chunk’s bump cursor when it can.

UTF-16 support requires the utf16 Cargo feature. Strict (validated) UTF-16 only — lone surrogates are rejected. The UTF-16 types interoperate with widestring::Utf16Str / widestring::Utf16String for I/O and FFI bridging. UTF-16 length and capacity are counted in u16 elements (matching widestring::Utf16Str::len()).

Example: UTF-8

use multitude::Arena;
use multitude::strings::RcStr;

let arena = Arena::new();

// Single-pointer immutable strings.
let s = arena.alloc_str_rc("hello, world");
assert_eq!(&*s, "hello, world");

// Build incrementally and freeze:
let mut b = arena.alloc_string();
b.push_str("abc");
b.push_str("123");
let frozen: RcStr = b.into_arena_str();
assert_eq!(&*frozen, "abc123");

// format!-style:
let name = "Alice";
let greeting = multitude::strings::format!(in &arena, "Hello, {name}!");
assert_eq!(&*greeting, "Hello, Alice!");

Example: UTF-16

use multitude::Arena;
use widestring::utf16str;

let arena = Arena::new();

// From a validated &Utf16Str literal:
let s = arena.alloc_utf16_str_rc(utf16str!("hello, world"));
assert_eq!(&*s, utf16str!("hello, world"));

// Or transcode from a &str:
let s2 = arena.alloc_utf16_str_rc_from_str("hello");
assert_eq!(&*s2, utf16str!("hello"));

// Build incrementally and freeze:
let mut b = arena.alloc_utf16_string();
b.push_str(utf16str!("abc"));
b.push_from_str("123");
let frozen = b.into_arena_utf16_str();
assert_eq!(&*frozen, utf16str!("abc123"));

// format!-style:
let name = "Alice";
let greeting = multitude::strings::format_utf16!(in &arena, "Hello, {name}!");
assert_eq!(greeting.as_utf16_str(), utf16str!("Hello, Alice!"));

Building DSTs

With the dst Cargo feature enabled, Arena exposes Arena::alloc_dst_arc / Arena::alloc_dst_rc / Arena::alloc_dst_box (and their try_* siblings) for constructing values whose layout is only known at runtime (custom DSTs, fat pointers, trait objects).

Each of these takes a Layout, a pointer-metadata value (e.g. a slice length, a DynMetadata), and a closure that initializes the buffer through a typed fat pointer. For most users, the dst-factory companion crate is the recommended high-level driver; the low-level interface looks like:

use core::alloc::Layout;

use multitude::Arena;

let arena = Arena::new();

// Allocate a 5-byte slice in the arena as a `Box<[u8]>`.
let layout = Layout::array::<u8>(5).unwrap();
let b: multitude::Box<[u8]> = unsafe {
    arena.alloc_dst_box::<[u8]>(layout, 5, |fat: *mut [u8]| {
        let p = fat.cast::<u8>();
        for i in 0..5 {
            p.add(i).write(i as u8);
        }
    })
};
assert_eq!(&*b, &[0, 1, 2, 3, 4]);

The same feature also enables eight Arena::alloc_slice_*_box methods that produce Box<[T]> directly (mirroring the existing _rc/_arc slice methods).

Crate Features