stack-arena

A fast, stack-like arena allocator for efficient memory management, implemented in Rust.

Features

• Efficient allocation of variable-sized objects with minimal overhead
• Memory is managed in chunks, automatically growing when needed, with old chunks preserved to maintain pointer validity
• Stack-like (LIFO) allocation and deallocation pattern
• Low-level memory management with minimal overhead
• Automatic chunk reuse for improved performance
• Implements the Allocator trait for compatibility with allocation APIs
• Suitable for parsers, interpreters, and other high-performance scenarios

When to Use

Stack-arena is ideal for scenarios where:

• You need to allocate many small objects in sequence
• Objects follow a stack-like (LIFO) allocation/deallocation pattern
• Memory usage needs to be minimized with low per-allocation overhead
• Performance is critical, especially for parsers, interpreters, or compilers
• You want to avoid the overhead of the system allocator for short-lived objects

Architecture

The library is organized in layers:

1. Chunk - The lowest level, representing a contiguous region of memory
2. BufferArena - Manages a single memory chunk with bump allocation
3. StackArena - Manages multiple chunks with LIFO allocation/deallocation
4. ObjectStack - High-level interface for building objects incrementally

Getting Started

Add to your Cargo.toml:

[dependencies]
stack-arena = "0.11"

Using ObjectStack (high-level API)

The ObjectStack provides a user-friendly interface for building and managing objects:

use stack_arena::ObjectStack;
use std::fmt::Write;

let mut stack = ObjectStack::new();

// Push a complete object
stack.push(b"hello ");

// Build an object incrementally
stack.extend("world");
write!(&mut stack, "!").unwrap();
let ptr = stack.finish();

// Access the object
let hello_world = unsafe { std::str::from_utf8_unchecked(ptr.as_ref()) };
assert_eq!(hello_world, "hello world!");

// Pop the object when done
stack.pop();

Using StackArena (low-level API)

The StackArena provides more control over memory allocation:

use stack_arena::{StackArena, Allocator};
use std::alloc::Layout;

// Create with default chunk size (4096 bytes)
let mut arena = StackArena::new();

// Or create with a custom chunk size
let mut custom_arena = StackArena::with_chunk_size(8192);

// Allocate memory
let layout = Layout::from_size_align(10, 1).unwrap();
let ptr = unsafe { arena.allocate(layout).unwrap() };

// Use the memory...
unsafe { std::ptr::write_bytes(ptr.as_ptr() as *mut u8, 0xAA, 10) };

// Deallocate when done
unsafe { arena.deallocate(ptr.cast(), layout) };

Performance

The library is optimized for scenarios with many small allocations that follow a stack-like pattern. Benchmarks show it significantly outperforms the system allocator in these cases:

• Up to 10x faster for consecutive small allocations
• Minimal overhead for allocation and deallocation
• Efficient memory reuse with the LIFO pattern
• Reduced memory fragmentation

Safety

• All returned pointers are valid until the corresponding object is deallocated
• Objects are stored in contiguous memory chunks
• Unsafe operations are used internally for performance
• The library follows LIFO (Last-In-First-Out) allocation pattern for efficiency
• Users must ensure proper memory safety when working with raw pointers

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT