Expand description
Arena-based generational allocation for Murk simulations.
Provides bump-allocated arenas with generation tracking for
efficient, deterministic memory management. This crate is one
of two that may contain unsafe code (along with murk-ffi).
§Architecture
The arena uses a double-buffered (“ping-pong”) design:
PingPongArena (orchestrator)
├── ArenaBuffer × 2 (alternating published/staging)
│ └── SegmentList → Segment[] (64MB bump-allocated Vec<f32>)
├── SparseSlab + sparse SegmentList (dedicated, not ping-pong'd)
├── Arc<StaticArena> (gen-0 forever, shared across vectorized envs)
├── ScratchRegion (per-tick temp space)
└── FieldDescriptor (FieldId → FieldEntry mapping, swapped on publish)§Field mutability classes
- PerTick: Fresh allocation each tick in the staging buffer.
- Sparse: Copy-on-write — shared until mutated, then new allocation.
- Static: Allocated once at world creation, shared via
Arc.
§Phase 1 safety
All allocations are Vec<f32> with zero-init. No MaybeUninit, no
unsafe. Phase 2 (after WP-4) will introduce bounded unsafe in
raw.rs for MaybeUninit + FullWriteGuard optimisation.
Re-exports§
pub use config::ArenaConfig;pub use error::ArenaError;pub use pingpong::PingPongArena;pub use pingpong::TickGuard;pub use read::OwnedSnapshot;pub use read::Snapshot;pub use scratch::ScratchRegion;pub use static_arena::StaticArena;
Modules§
- config
- Arena configuration parameters.
- descriptor
- Field descriptor mapping:
FieldId→(FieldHandle, metadata). - error
- Arena-specific error types.
- handle
- Field handles and location descriptors.
- pingpong
- Double-buffered ping-pong arena orchestrator.
- read
- Read-only snapshot view of a published arena generation.
- scratch
- Per-tick scratch space for temporary propagator allocations.
- segment
- Contiguous memory segments and growable segment lists.
- sparse
- Sparse slab allocator for copy-on-write fields.
- static_
arena - Static generation-0 arena for immutable fields.
- write
- Mutable arena access for the staging buffer during a tick.