safe_bump/lib.rs
1//! Safe bump-pointer arena allocator.
2//!
3//! `safe-bump` provides two typed arena allocators built entirely with safe
4//! Rust (zero `unsafe` blocks). Values are allocated and accessed via stable
5//! [`Idx<T>`] indices.
6//!
7//! # Arena types
8//!
9//! - [`Arena<T>`] — single-thread, zero overhead, backed by [`Vec<T>`]
10//! - [`SharedArena<T>`] — thread-safe (`Send + Sync`), wait-free reads,
11//! concurrent allocation via `&self`
12//!
13//! Both types share the same [`Idx<T>`] and [`Checkpoint<T>`] types, support
14//! checkpoint/rollback, and run destructors on rollback/reset/drop.
15//!
16//! # Key properties
17//!
18//! - **Zero `unsafe`**: enforced by `#![forbid(unsafe_code)]`
19//! - **Auto [`Drop`]**: destructors run on reset, rollback, and arena drop
20//! - **Checkpoint/rollback**: save state and discard speculative allocations
21//! - **Thread-safe**: [`SharedArena<T>`] supports concurrent allocation
22//!
23//! # Example
24//!
25//! ```
26//! use safe_bump::{Arena, Idx};
27//!
28//! let mut arena: Arena<String> = Arena::new();
29//! let a: Idx<String> = arena.alloc(String::from("hello"));
30//! let b: Idx<String> = arena.alloc(String::from("world"));
31//!
32//! assert_eq!(arena[a], "hello");
33//! assert_eq!(arena[b], "world");
34//!
35//! let cp = arena.checkpoint();
36//! let _tmp = arena.alloc(String::from("temporary"));
37//! arena.rollback(cp); // "temporary" is dropped
38//! assert_eq!(arena.len(), 2);
39//! ```
40//!
41//! # References
42//!
43//! - Hanson, 1990 — "Fast Allocation and Deallocation of Memory
44//! Based on Object Lifetimes"
45
46#![forbid(unsafe_code)]
47#![deny(missing_docs)]
48
49mod arena;
50mod checkpoint;
51mod chunked_storage;
52mod idx;
53mod iter;
54mod shared_arena;
55
56pub use arena::Arena;
57pub use checkpoint::Checkpoint;
58pub use idx::Idx;
59pub use iter::{IterIndexed, IterIndexedMut};
60pub use shared_arena::{SharedArena, SharedArenaIter, SharedArenaIterIndexed};
61
62#[cfg(test)]
63mod tests;