# stack-arena
[](https://crates.io/crates/stack-arena)
[](https://docs.rs/stack-arena)
[](https://opensource.org/licenses/MIT)
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`:
```toml
[dependencies]
stack-arena = "0.9"
```
### Using ObjectStack (high-level API)
The `ObjectStack` provides a user-friendly interface for building and managing objects:
```rust
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:
```rust
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