Crate arena_alligator

Expand description

Arena allocator for building bytes::Bytes without copying the final payload.

Write into a Buffer, call freeze(), and get back Bytes backed by arena memory. The slot or block returns to the arena when the last Bytes reference drops.

§Arena selection

FixedArena is the recommended high-throughput path when one slot size covers the workload. Fixed uses uniform slots and a bitmap claim path.

BuddyArena covers variable-size allocation from one shared region. Requests are rounded up to powers of two, larger blocks split on demand, and neighbors coalesce on release.

Both produce the same Buffer type with identical write and freeze semantics.

§Quick start

use core::num::NonZeroUsize;
use arena_alligator::FixedArena;
use bytes::BufMut;

let arena = FixedArena::with_slot_capacity(
    NonZeroUsize::new(1024).unwrap(),
    NonZeroUsize::new(4096).unwrap(),
)
    .build()
    .unwrap();

let mut buf = arena.allocate().unwrap();
buf.put_slice(b"hello");
let bytes = buf.freeze();
assert_eq!(&bytes[..], b"hello");

§Auto-spill

.auto_spill() changes overflow writes from panic-on-capacity to heap spill. The arena allocation is released as soon as the spill happens.

§Initialization policy

The default policy is InitPolicy::Uninit, which matches Rust’s common writable-uninitialized-memory model: newly allocated capacity is not zero-filled, and only the bytes written become visible in the frozen Bytes.

InitPolicy::Zero zeroes memory on return to the arena and on first allocation. Returned slots and blocks are scrubbed before being marked free, preventing data leaks between callers. First allocations (cold memory, never returned) are zeroed on the alloc path. Memory that has been through a return-scrub cycle is no longer cold and the alloc-path zero is skipped. All zeroing uses the zeroize crate (compiler-guaranteed not elided).

§Frozen slice retention

Freezing a buffer transfers ownership of the arena slot (or buddy block) to the returned Bytes. Cloning or slicing that Bytes shares the reference, so the arena memory stays pinned until every clone and slice is dropped.

BytesExt::into_owned() copies frozen bytes into fresh owned mutable storage.

§Preallocated memory handoff

FixedArena::from_raw() and BuddyArena::from_raw() let callers hand pre-existing memory to the arena. This is for mmap’d regions, shared memory, static buffers, and similar cases where the backing storage is provisioned elsewhere.

For &'static mut buffers, prefer the safe FixedArena::from_static() and BuddyArena::from_static() wrappers. Use from_raw() for pointer/length regions and custom deallocation strategies.

These constructors are unsafe because the arena cannot validate pointer provenance, exclusivity, or deallocation correctness. On the safe side of the boundary, the resulting arenas use the same allocation, freeze, and retention rules as the ordinary builder paths.

Use NoDealloc when the caller retains responsibility for freeing the backing region. Use HeapDealloc when the region came from alloc::alloc::alloc.

§Async allocation

With the async-alloc feature, AsyncFixedArena and AsyncBuddyArena provide allocate_async(), which parks until capacity is available. The buddy variant returns a Result and fails fast with AllocError::RequestTooLarge for a request larger than the arena could ever satisfy, rather than parking forever.

§`no_std`

This crate is #![no_std] by default and depends only on alloc and core. It works on targets with a global allocator and pointer-width atomics, including embedded systems.

§Feature flags

Feature	Default	What it enables
`std`	yes	Standard-library integrations and dependency features; required by `async-alloc`
`libc`	yes	Page size detection via `sysconf` on Unix
`async-alloc`	no	`AsyncFixedArena` / `AsyncBuddyArena` via tokio (implies `std`)
`hazmat-raw-access`	no	Raw pointer access to arena memory

For no_std usage, disable default features:

[dependencies]
arena-alligator = { version = "0.6", default-features = false }

Modules§

hazmat: Low-level zero-copy access to arena memory.

Structs§

AsyncBuddyArena: Async-capable wrapper around BuddyArena.
AsyncFixedArena: Async-capable wrapper around FixedArena.
AutoSpill: Typestate marker for auto-spill builder mode.
BuddyArena: Buddy-backed arena allocator.
BuddyArenaBuilder: Builder for BuddyArena.
BuddyArenaMetrics: Snapshot of buddy arena metrics.
BuddyGeometry: Validated buddy arena geometry.
Buffer: A writable buffer backed by arena memory.
BufferFullError: Buffer capacity exceeded.
FixedArena: Fixed-size slot arena allocator.
FixedArenaBuilder: Builder for FixedArena.
FixedArenaMetrics: Snapshot of fixed arena metrics.
HazmatRaw: Typestate marker for hazmat raw-access builder mode.
HeapDealloc: Frees memory via alloc::alloc::dealloc with the stored Layout.
NoDealloc: No-op deallocator for caller-managed memory.
NotifyWaiters: Per-order waiter system.
RawBackedBuddyArenaBuilder: Builder for a buddy arena backed by user-provided memory.
RawBackedFixedArenaBuilder: Builder for a fixed arena backed by user-provided memory.
Standard: Typestate marker for the default builder mode.
Unfaulted: An arena whose backing pages have not yet been faulted.

Enums§

AllocError: Allocation failed.
BuddyHint: Hint for deriving buddy geometry from caller-provided memory.
BuildError: Builder configuration error.
InitPolicy: Initialization policy for arena memory.
PageSize: Page size used for prefaulting the arena backing allocation.
SlotSpec: How to slice caller-provided memory into fixed-size slots.

Traits§

BuddyWaiter: Wait strategy for buddy arena async allocation.
BytesExt: Extension methods for converting Bytes into owned mutable storage.
Dealloc: Strategy for deallocating arena backing memory.
WaitRegistration: Registration returned by waiter traits.
Waiter: Wait strategy for fixed arena async allocation.