arena-b

A high-performance bump allocator for Rust, designed for scenarios where you need to allocate many temporary objects and deallocate them all at once. Ideal for parsers, game engines, compilers, and request-scoped web server data.

Overview

Arena allocation follows a simple principle: allocate objects sequentially into a contiguous buffer, then free everything simultaneously when the arena is reset or dropped. This approach eliminates per-object deallocation overhead and avoids memory fragmentation entirely.

Quick Start

use arena_b::Arena;

fn main() {
    let arena = Arena::new();
    
    // Allocate objects into the arena
    let numbers: Vec<&u32> = (0..1000)
        .map(|i| arena.alloc(i))
        .collect();
    
    // All allocations are freed when the arena is dropped
    // Alternatively, call arena.reset() to free manually
}

Features

• High Performance: Bump allocation with thread-local caching and lock-free fast paths
• Memory Safety: Unsafe internals are carefully encapsulated and thoroughly tested
• Checkpoint API: Save and restore allocation state for frame-based or request-scoped patterns
• Zero-Cost Abstractions: Optional features incur no overhead when disabled
• Adaptive Capacity Controls (v0.7): reserve_additional, shrink_to_fit, and reset_and_shrink let you grow ahead of allocation spikes and release memory afterward
• Lock-Free Object Pool (v0.8): Generic LockFreePool<T> for zero-contention object reuse in high-frequency allocation patterns
• Advanced Debugging (v0.6): Leak detection, validation hooks, and optional backtraces make it easier to audit arena usage during development
• Virtual Memory Instrumentation (v0.6): Inspect committed bytes at runtime and rely on improved macOS/Windows handling for large reserves

What's New in v0.8

• Generic Lock-Free Pool: LockFreePool<T> provides thread-safe object pooling with atomic CAS operations for game engines, parsers, and high-frequency allocation patterns
• Lock-Free Allocator Control: LockFreeAllocator with runtime enable()/disable() switching and cache_hit_rate() monitoring
• Thread-Local Slabs: ThreadSlab with generation-based invalidation for per-thread fast-path allocations
• Enhanced Statistics: LockFreeStats now supports cache_hit_rate(), record_deallocation(), and is Cloneable for snapshots
• Debug Improvements: DebugStats includes leak_reports counter for tracking leak detection calls

What's New in v0.7

• Proactive Reservation: Call Arena::reserve_additional(bytes) to pre-grow the underlying chunk before a known burst of allocations, reducing contention in hot paths.
• Memory Trimming: Arena::shrink_to_fit and Arena::reset_and_shrink reclaim any extra chunks after a spike, keeping long-running services lean.
• Docs & Tooling: README and changelog now cover the adaptive APIs, and CI stays green with the explicit Clippy allowance on alloc_str_uninit.

What's New in v0.6

• New Allocation APIs: alloc_slice_fast accelerates small slice copies and alloc_str_uninit creates mutable UTF-8 buffers without extra allocations.
• Virtual Memory Telemetry: virtual_memory_committed_bytes() reports the current committed footprint, while rewinds/resets now guarantee proper decommit on every platform.
• Lock-Free Overhaul: Per-thread slab caches reduce contention and eliminate previously observed race conditions in the lock-free buffer.
• Panic-Safe Scopes: Arena::scope now rolls back automatically even if the scoped closure unwinds, ensuring arenas remain consistent under failure.
• Enhanced Debugging: Runtime validation hooks, leak reports, and optional debug_backtrace capture provide deep diagnostics when the debug feature is enabled.

What's New in v0.5

• Checkpoints: Mark allocation points and rewind instantly for bulk deallocation
• Debug Mode: Detect use-after-free bugs with guard patterns and pointer validation
• Virtual Memory: Reserve large address spaces without committing physical memory upfront
• Thread-Local Caching: Reduce lock contention in multi-threaded workloads
• Lock-Free Operations: Minimize synchronization overhead in high-contention scenarios

Installation

Add to your Cargo.toml:

[dependencies]
arena-b = "0.8"

Or via the command line:

cargo add arena-b

Feature Flags

Enable features based on your requirements:

# Basic bump allocator
arena-b = "0.8"

# With debug safety checks (recommended for development)
arena-b = { version = "0.8", features = ["debug"] }

# Full feature set for maximum performance
arena-b = { version = "0.8", features = ["debug", "virtual_memory", "thread_local", "lockfree"] }

Usage Examples

Frame-Based Allocation

Suitable for game loops or per-request processing:

use arena_b::Arena;

fn game_loop() {
    let arena = Arena::new();
    
    loop {
        let checkpoint = arena.checkpoint();
        
        // Allocate frame-specific data
        let entities = allocate_entities(&arena);
        let particles = allocate_particles(&arena);
        
        // Process the frame...
        
        // Deallocate all frame data at once
        unsafe { arena.rewind_to_checkpoint(checkpoint); }
    }
}

AST Construction for Parsers

Build complex data structures without manual memory management:

use arena_b::Arena;

struct AstNode<'a> {
    value: String,
    children: Vec<&'a AstNode<'a>>,
}

fn parse_expression<'a>(input: &str, arena: &'a Arena) -> &'a AstNode<'a> {
    let node = arena.alloc(AstNode {
        value: input.to_string(),
        children: Vec::new(),
    });
    
    // Child nodes are allocated in the same arena
    // All memory is freed when the arena is dropped
    
    node
}

Thread-Safe Allocation

Use SyncArena for concurrent access:

use std::sync::Arc;
use arena_b::SyncArena;

fn main() {
    let arena = Arc::new(SyncArena::new());
    
    let handles: Vec<_> = (0..4)
        .map(|_| {
            let arena = Arc::clone(&arena);
            std::thread::spawn(move || {
                arena.scope(|scope| {
                    scope.alloc("thread-local data")
                })
            })
        })
        .collect();
    
    for handle in handles {
        handle.join().unwrap();
    }
}

Performance Characteristics

Typical performance improvements over standard allocation:

• vs Box: 10–50× faster for allocation-intensive workloads
• vs Vec: 5–20× faster when bulk reset is applicable
• Memory overhead: ~64 bytes per chunk; negligible per-allocation overhead
• Thread contention: Minimal when thread-local features are enabled

Run benchmarks locally:

cargo bench

When to Use arena-b

Recommended Use Cases:

• Parsers and compilers (ASTs, intermediate representations)
• Game engines (per-frame temporary allocations)
• Web servers (per-request data structures)
• Any workload with many short-lived objects

Less Suitable For:

• Long-lived objects with heterogeneous lifetimes
• Applications with minimal allocation requirements
• Scenarios requiring fine-grained memory control

API Reference

use arena_b::Arena;

let arena = Arena::new();

// Basic allocation
let number = arena.alloc(42u32);
let string = arena.alloc_str("hello world");
let small = arena.alloc_slice_fast(&[1u8, 2, 3]);
let buf = arena.alloc_str_uninit(256); // mutable UTF-8 buffer

// Scoped allocation with automatic cleanup (panic-safe)
arena.scope(|scope| {
    let temp = scope.alloc("temporary data");
    // Automatically rewound even if this closure panics
    assert_eq!(temp, &"temporary data");
});

// Checkpoint-based bulk deallocation
let checkpoint = arena.checkpoint();
// ... perform allocations ...
unsafe { arena.rewind_to_checkpoint(checkpoint); }

// Virtual memory telemetry (feature = "virtual_memory")
#[cfg(feature = "virtual_memory")]
if let Some(bytes) = arena.virtual_memory_committed_bytes() {
    println!("Currently committed: {} bytes", bytes);
}

// Statistics
println!("Allocated: {} bytes", arena.bytes_allocated());
println!("Stats: {:?}", arena.stats());

Documentation

Additional documentation is available in the docs/ directory:

• docs/guide.md — Comprehensive usage guide
• docs/strategies.md — Allocation strategy selection
• docs/advanced.md — Advanced configuration options
• docs/architecture.md — Internal design and implementation details

Examples

Working examples are provided in the examples/ directory:

• parser_expr.rs — Expression parser with arena-allocated AST
• game_loop.rs — Game loop with frame-based allocation
• graph_pool.rs — Graph traversal with object pooling
• string_intern.rs — String interning implementation
• v0.5_features.rs — Demonstration of v0.5 features

Contributing

Contributions are welcome. Please consider the following:

• Bug reports and feature requests via GitHub Issues
• Performance improvements with benchmark data
• Documentation corrections and improvements
• For significant changes, please open an issue for discussion first

License

Licensed under the MIT License. See LICENSE for details.

Changelog

See CHANGELOG.md for complete version history.

v0.8.0

• Generic LockFreePool<T> for thread-safe object pooling
• LockFreeAllocator with runtime enable/disable control
• ThreadSlab for per-thread fast-path allocations
• Enhanced LockFreeStats with cache_hit_rate() and Clone
• DebugStats now includes leak_reports field

v0.7.0

• reserve_additional for proactive capacity growth
• shrink_to_fit and reset_and_shrink for memory trimming

v0.6.0

• AVX2/NEON SIMD optimizations
• alloc_slice_fast and alloc_str_uninit APIs
• Virtual memory telemetry and cross-platform fixes
• Panic-safe scopes

v0.5.0

• Checkpoint and rewind API for bulk deallocation
• Debug mode with memory safety validation
• Virtual memory support for large allocations
• Thread-local caching and lock-free operations