murk_arena/lib.rs
1//! Arena-based generational allocation for Murk simulations.
2//!
3//! Provides bump-allocated arenas with generation tracking for
4//! efficient, deterministic memory management. This crate is one
5//! of two that may contain `unsafe` code (along with `murk-ffi`).
6//!
7//! # Architecture
8//!
9//! The arena uses a double-buffered ("ping-pong") design:
10//!
11//! ```text
12//! PingPongArena (orchestrator)
13//! ├── ArenaBuffer × 2 (alternating published/staging)
14//! │ └── SegmentList → Segment[] (64MB bump-allocated Vec<f32>)
15//! ├── SparseSlab + sparse SegmentList (dedicated, not ping-pong'd)
16//! ├── Arc<StaticArena> (gen-0 forever, shared across vectorized envs)
17//! ├── ScratchRegion (per-tick temp space)
18//! └── FieldDescriptor (FieldId → FieldEntry mapping, swapped on publish)
19//! ```
20//!
21//! # Field mutability classes
22//!
23//! - **PerTick:** Fresh allocation each tick in the staging buffer.
24//! - **Sparse:** Copy-on-write — shared until mutated, then new allocation.
25//! - **Static:** Allocated once at world creation, shared via `Arc`.
26//!
27//! # Phase 1 safety
28//!
29//! All allocations are `Vec<f32>` with zero-init. No `MaybeUninit`, no
30//! `unsafe`. Phase 2 (after WP-4) will introduce bounded `unsafe` in
31//! `raw.rs` for `MaybeUninit` + `FullWriteGuard` optimisation.
32
33#![deny(missing_docs)]
34#![deny(rustdoc::broken_intra_doc_links)]
35#![deny(unsafe_code)]
36
37pub mod config;
38pub mod descriptor;
39pub mod error;
40pub mod handle;
41pub mod pingpong;
42mod raw;
43pub mod read;
44pub mod scratch;
45pub mod segment;
46pub mod sparse;
47pub mod static_arena;
48pub mod write;
49
50// Public re-exports for the primary API surface.
51pub use config::ArenaConfig;
52pub use error::ArenaError;
53pub use pingpong::{PingPongArena, TickGuard};
54pub use read::{OwnedSnapshot, Snapshot};
55pub use scratch::ScratchRegion;
56pub use static_arena::{SharedStaticArena, StaticArena};