Struct Arena 

pub struct Arena { /* private fields */ }

A dual-end bump-allocated arena.

Owns or borrows a fixed-size buffer of bytes. Two bump pointers track allocation positions at each end. The bottom end grows from low addresses upward. The top end grows from high addresses downward. Allocation fails when the two pointers would meet.

The arena is not the program’s #[global_allocator] and is not intended to be one. It is designed for scoped per-region or per-thread use through BottomHandle and TopHandle, which the host passes to allocator-aware collection constructors. The standard global allocator continues to handle every allocation that does not route through an arena handle. Hosts that want every allocation in the program to be arena-backed must wrap the arena in a thread-safe allocator and install it via #[global_allocator]; this crate does not provide such a wrapper because doing so well requires choices that depend on the host’s threading and synchronization model.

Generations and stale-pointer detection

The arena carries an epoch counter that increments on Arena::reset. The ArenaHandle family of safe wrappers captures the epoch at construction and validates it on access, returning Stale if the arena has been reset since the handle was issued. The counter is u64 and uses checked arithmetic. A saturated counter halts the arena’s reset path with EpochSaturated. Saturation requires roughly five hundred eighty four thousand years at one reset per microsecond and is documentation rather than a real failure mode in expected use.

In-process recovery from saturation is possible through Arena::force_reset_epoch, which is unsafe and requires the caller to certify that no ArenaHandle from any prior epoch is reachable. Cross-process recovery for very long-lived deployments uses checkpoint and restart against host-owned non-volatile storage. ArenaHandle is intentionally not serializable because its pointer is not stable across processes.

See the crate-level documentation for the design overview.

Implementations

impl Arena

pub fn with_capacity(capacity: usize) -> Arena

Create an arena backed by a freshly allocated heap buffer of the given byte capacity.

Available only with the alloc feature. The buffer is zeroed at construction and is allocated with 16-byte alignment, which covers the alignment requirements of i64, f64, u128, and most platform-native pointers and primitives.

Panics on allocation failure via the standard handle_alloc_error path. A capacity of zero produces an arena that satisfies allocation requests for zero-size layouts only; non-zero allocations return AllocError.

Examples

use allocator_api2::vec::Vec as ArenaVec;
use keleusma_arena::Arena;

let arena = Arena::with_capacity(1024);
let mut v: ArenaVec<i64, _> = ArenaVec::new_in(arena.stack_handle());
v.push(1);
v.push(2);
v.push(3);
assert_eq!(v.len(), 3);
assert!(arena.bottom_used() >= 24);

Examples found in repository

examples/generic_match.rs (line 16)

fn run(label: &str, src: &str) -> Value {
    let tokens = tokenize(src).expect("lex");
    let program = parse(&tokens).expect("parse");
    let module = compile(&program).expect("compile");
    let arena = Arena::with_capacity(DEFAULT_ARENA_CAPACITY);
    let mut vm = Vm::new(module, &arena).expect("verify");
    match vm.call(&[]) {
        Ok(VmState::Finished(v)) => {
            println!("{}: {:?}", label, v);
            v
        }
        other => panic!("{}: {:?}", label, other),
    }
}

examples/target_aware_compile.rs (line 90)

fn compile_and_run(src: &str, target: &Target) {
    let tokens = tokenize(src).expect("lex");
    let program = parse(&tokens).expect("parse");
    let module = compile_with_target(&program, target).expect("compile");
    let arena = Arena::with_capacity(DEFAULT_ARENA_CAPACITY);
    let mut vm = Vm::new(module, &arena).expect("verify");
    match vm.call(&[]).expect("call") {
        VmState::Finished(v) => println!("  result: {:?}", v),
        other => panic!("unexpected: {:?}", other),
    }
    let _ = Value::Unit;
}

examples/generic_identity.rs (line 27)

fn main() {
    let src = r#"
        fn id<T>(x: T) -> T { x }
        fn main() -> i64 { id(42) }
    "#;
    let tokens = tokenize(src).expect("lex");
    let program = parse(&tokens).expect("parse");
    let module = compile(&program).expect("compile");
    let arena = Arena::with_capacity(DEFAULT_ARENA_CAPACITY);
    let mut vm = Vm::new(module, &arena).expect("verify");
    match vm.call(&[]) {
        Ok(VmState::Finished(Value::Int(n))) => {
            println!("id(42) = {}", n);
            assert_eq!(n, 42);
            println!("generic identity executed end to end");
        }
        other => panic!("unexpected: {:?}", other),
    }
}

examples/generic_struct.rs (line 28)

fn main() {
    let src = r#"
        struct Cell<T> { value: T }
        fn main() -> i64 {
            let c = Cell { value: 42 };
            c.value
        }
    "#;
    let tokens = tokenize(src).expect("lex");
    let program = parse(&tokens).expect("parse");
    let module = compile(&program).expect("compile");
    let arena = Arena::with_capacity(DEFAULT_ARENA_CAPACITY);
    let mut vm = Vm::new(module, &arena).expect("verify");
    match vm.call(&[]) {
        Ok(VmState::Finished(Value::Int(n))) => {
            println!("Cell {{ value: 42 }}.value = {}", n);
            assert_eq!(n, 42);
            println!("generic struct executed end to end");
        }
        other => panic!("unexpected: {:?}", other),
    }
}

examples/method_call.rs (line 32)

fn main() {
    let src = r#"
        trait Doubler { fn double(x: i64) -> i64; }
        impl Doubler for i64 { fn double(x: i64) -> i64 { x + x } }
        fn main() -> i64 {
            let n: i64 = 21;
            n.double()
        }
    "#;
    let tokens = tokenize(src).expect("lex");
    let program = parse(&tokens).expect("parse");
    let module = compile(&program).expect("compile");
    let arena = Arena::with_capacity(DEFAULT_ARENA_CAPACITY);
    let mut vm = Vm::new(module, &arena).expect("verify");
    match vm.call(&[]) {
        Ok(VmState::Finished(Value::Int(n))) => {
            println!("21.double() = {}", n);
            assert_eq!(n, 42);
            println!("method call dispatch executed end to end");
        }
        other => panic!("unexpected: {:?}", other),
    }
}

examples/monomorphize_generic_method.rs (line 31)

fn main() {
    let src = r#"
        trait Doubler { fn double(x: i64) -> i64; }
        impl Doubler for i64 { fn double(x: i64) -> i64 { x + x } }
        fn use_doubler<T: Doubler>(x: T) -> i64 { x.double() }
        fn main() -> i64 { use_doubler(21) }
    "#;
    let tokens = tokenize(src).expect("lex");
    let program = parse(&tokens).expect("parse");
    let module = compile(&program).expect("compile");
    let arena = Arena::with_capacity(DEFAULT_ARENA_CAPACITY);
    let mut vm = Vm::new(module, &arena).expect("verify");
    match vm.call(&[]) {
        Ok(VmState::Finished(Value::Int(n))) => {
            println!("use_doubler(21) = {}", n);
            assert_eq!(n, 42);
            println!("monomorphization-driven method dispatch executed end to end");
        }
        other => panic!("unexpected: {:?}", other),
    }
}

Additional examples can be found in:

• examples/struct_method_dispatch.rs
• examples/wcmu_rejection.rs
• examples/string_ops.rs
• examples/zero_copy_include_bytes.rs
• examples/wcmu_basic.rs
• examples/yield_error.rs
• examples/wcmu_attestation.rs

pub fn from_static_buffer(buffer: &'static mut [u8]) -> Arena

Create an arena backed by a static buffer.

The buffer must outlive the arena. The 'static mut requirement satisfies this for typical embedded patterns where the buffer is a static array placed in BSS or DATA. For shorter-lived buffers, see Arena::from_buffer_unchecked.

pub unsafe fn from_buffer_unchecked(ptr: *mut u8, capacity: usize) -> Arena

Create an arena from a raw pointer and length.

The buffer’s base alignment does not need to match the alignment of any particular allocation type. The arena computes alignment against the actual buffer base address and pads as needed for each aligned allocation.

Safety

The caller must uphold the following.

• ptr is non-null.
• ptr is valid for reads and writes of capacity bytes for the entire lifetime of the returned arena.
• No other code accesses the buffer through any path that would alias with the arena’s allocations during the arena’s lifetime.

This constructor is the only path that admits buffers with non-'static lifetimes. It exists for embedded contexts where the lifetime is known statically through other means but the type system cannot express it. Most callers should prefer Arena::from_static_buffer.

pub fn capacity(&self) -> usize

Total capacity of the arena in bytes.

Examples found in repository

examples/wcmu_basic.rs (line 46)

fn main() {
    // Compile.
    let tokens = tokenize(SCRIPT).expect("lex error");
    let program = parse(&tokens).expect("parse error");
    let module = compile(&program).expect("compile error");

    // Inspect the WCMU budget for each Stream chunk in the module.
    let chunk_wcmu = verify::module_wcmu(&module, &[]).expect("module wcmu");
    for (idx, chunk) in module.chunks.iter().enumerate() {
        if matches!(chunk.block_type, keleusma::bytecode::BlockType::Stream) {
            let (stack_bytes, heap_bytes) = chunk_wcmu[idx];
            println!("chunk `{}`:", chunk.name);
            println!("  stack WCMU: {} bytes", stack_bytes);
            println!("  heap  WCMU: {} bytes", heap_bytes);
            println!("  total:      {} bytes", stack_bytes + heap_bytes);
        }
    }

    // Construct an auto-sized arena and a Vm that borrows it.
    let cap = keleusma::vm::auto_arena_capacity_for(&module, &[]).expect("auto capacity");
    let arena = keleusma::Arena::with_capacity(cap);
    let mut vm = Vm::new(module, &arena).expect("vm construction");
    println!();
    println!("auto-sized arena capacity: {} bytes", vm.arena().capacity());

    // Drive the coroutine through one yield.
    match vm.call(&[Value::Int(21)]).expect("vm call") {
        VmState::Yielded(v) => println!("yielded: {:?}", v),
        other => panic!("expected yield, got {:?}", other),
    }
}

examples/wcmu_attestation.rs (line 70)

fn main() {
    // Compile.
    let tokens = tokenize(SCRIPT).expect("lex error");
    let program = parse(&tokens).expect("parse error");
    let module = compile(&program).expect("compile error");

    // Inspect the WCMU budget with no native attestation. Heap is zero.
    let chunk_wcmu_default = verify::module_wcmu(&module, &[]).expect("module wcmu");
    println!("Default attestation (no host declaration):");
    for (idx, chunk) in module.chunks.iter().enumerate() {
        if matches!(chunk.block_type, keleusma::bytecode::BlockType::Stream) {
            let (s, h) = chunk_wcmu_default[idx];
            println!("  chunk `{}`: stack {} heap {}", chunk.name, s, h);
        }
    }

    // Inspect with the host's declared attestation. Heap reflects the
    // bound the host promises the native will not exceed.
    let attested_native_wcmu = [256u32];
    let chunk_wcmu_attested =
        verify::module_wcmu(&module, &attested_native_wcmu).expect("module wcmu");
    println!();
    println!("Attested host::compute_value with 256 bytes:");
    for (idx, chunk) in module.chunks.iter().enumerate() {
        if matches!(chunk.block_type, keleusma::bytecode::BlockType::Stream) {
            let (s, h) = chunk_wcmu_attested[idx];
            println!("  chunk `{}`: stack {} heap {}", chunk.name, s, h);
        }
    }

    // Construct a Vm with adequate capacity.
    let arena = keleusma::Arena::with_capacity(4096);
    let mut vm = Vm::new(module, &arena).expect("vm construction");

    // Register the native and declare its WCET and WCMU bounds.
    vm.register_fn("host::compute_value", |x: i64| -> i64 { x * 3 });
    vm.set_native_bounds("host::compute_value", 25, 256)
        .expect("set bounds");

    // Re-verify resources with the declared attestations now in place.
    vm.verify_resources().expect("verify_resources");
    println!();
    println!(
        "verify_resources succeeded with arena {} bytes",
        vm.arena().capacity()
    );

    // Drive the coroutine through one yield.
    match vm.call(&[Value::Int(7)]).expect("vm call") {
        VmState::Yielded(v) => println!("yielded: {:?}", v),
        other => panic!("expected yield, got {:?}", other),
    }
}

pub fn bottom_used(&self) -> usize

Bytes currently allocated from the bottom end.

pub fn top_used(&self) -> usize

Bytes currently allocated from the top end.

pub fn free(&self) -> usize

Bytes available for either end to consume.

pub fn bottom_peak(&self) -> usize

Highest observed bottom usage in bytes since arena creation or the most recent Arena::clear_peaks call.

pub fn top_peak(&self) -> usize

Highest observed top usage in bytes since arena creation or the most recent Arena::clear_peaks call.

pub fn bottom_mark(&self) -> BottomMark

Return a snapshot of the bottom-end bump pointer for later use with Arena::rewind_bottom.

pub fn top_mark(&self) -> TopMark

Return a snapshot of the top-end bump pointer for later use with Arena::rewind_top.

pub fn reset(&mut self) -> Result<(), EpochSaturated>

Reset both ends, reclaiming all allocations.

Constant-time. Does not zero the buffer contents because subsequent allocations will overwrite as needed. Does not clear peak watermarks; use Arena::clear_peaks for that.

Advances the epoch counter, invalidating every outstanding ArenaHandle. Returns EpochSaturated if the counter is already at u64::MAX. See Arena::force_reset_epoch for recovery.

Takes &mut self so the borrow checker prevents calling reset while any handle borrows the arena. This guarantees no live allocations through Allocator trait users at the moment of reset.

pub unsafe fn reset_unchecked(&self) -> Result<(), EpochSaturated>

Reset both ends and advance the epoch through a shared reference.

Companion to Arena::reset for callers that hold the arena through a shared reference and cannot temporarily acquire exclusive access. The interior-mutable bump pointers and epoch counter make the implementation race-free for single-threaded use.

Safety

The caller must certify that no allocator-bound collection holds storage in the arena at the moment of reset. Concretely, no allocator_api2::vec::Vec<T, BottomHandle> or allocator_api2::vec::Vec<T, TopHandle> value may have non-zero capacity when this is called. Outstanding ArenaHandle values are correctly invalidated by the epoch advance and remain safe.

Returns EpochSaturated when the epoch counter is at u64::MAX. Recovery is via Arena::force_reset_epoch.

pub unsafe fn reset_top_unchecked(&self) -> Result<(), EpochSaturated>

Reset the top end and advance the epoch through a shared reference, leaving the bottom end untouched.

Intended for hosts that use the bottom end for long-lived allocator-bound collections (such as an operand stack) while using the top end for short-lived scratch (such as dynamic strings). The epoch advance invalidates every outstanding ArenaHandle regardless of which end produced it. This is the desired discipline because handles do not record which end they came from and any handle that survives a reset is by definition stale.

Safety

The caller must certify that no allocator-bound collection holds storage in the top end at the moment of reset. Bottom-end allocator-bound collections are unaffected by this call and retain their storage. Outstanding ArenaHandle values are correctly invalidated by the epoch advance and remain safe.

Returns EpochSaturated when the epoch counter is at u64::MAX. Recovery is via Arena::force_reset_epoch.

pub fn epoch(&self) -> u64

Current epoch counter value.

Captured by ArenaHandle at construction and compared on access. Hosts performing long-running missions may consult this alongside Arena::epoch_remaining to schedule a graceful restart well before saturation.

pub fn epoch_remaining(&self) -> u64

Number of resets remaining before the epoch counter saturates.

pub unsafe fn force_reset_epoch(&mut self)

Reset the epoch counter to zero.

Recovery path for EpochSaturated. Resets bump pointers as well so the arena is in the same observable state as a freshly constructed arena, except for retained capacity.

Safety

The caller must certify that no ArenaHandle produced under any prior epoch is reachable. Calling this while such handles exist invalidates the stale-detection guarantee and may permit use after invalidation that the type system would otherwise catch through epoch comparison.

The intended use is recovery after a Arena::reset call has returned EpochSaturated. The host halts every consumer of the arena, drains every cache that holds an ArenaHandle, and only then invokes this method.

pub fn clear_peaks(&mut self)

Clear the peak watermarks for both ends.

Sets each peak to the current pointer value. After this call, peak readings reflect only allocations made after the call.

pub unsafe fn rewind_bottom(&self, mark: BottomMark)

Rewind the bottom end to a previously recorded mark.

Safety

The caller must ensure that no live values reference memory in the range [mark.0, current_bottom_top). References obtained through the Allocator trait, including those held by allocator_api2::vec::Vec and similar collections, must be dropped or otherwise abandoned before this call. Subsequent allocations may overwrite the rewound region, which would alias with any retained reference and produce undefined behavior.

Marks from a different arena are a logic error.

pub unsafe fn rewind_top(&self, mark: TopMark)

Rewind the top end to a previously recorded mark.

Safety

Same contract as Arena::rewind_bottom.

pub unsafe fn reset_bottom(&self)

Clear the bottom end without checking for live references.

Safety

The caller must ensure no live references into the bottom region exist. Equivalent to Arena::rewind_bottom with a mark of zero, with the same safety contract.

pub unsafe fn reset_top(&self)

Clear the top end without checking for live references.

Safety

The caller must ensure no live references into the top region exist. Equivalent to Arena::rewind_top with a mark of capacity, with the same safety contract.

pub fn fits_budget(&self, budget: &Budget) -> bool

Returns true if the given budget fits within the arena’s capacity. The check is budget.bottom_bytes + budget.top_bytes <= capacity.

This is the generic budget contract referenced in the crate documentation. Producers compute a budget through whatever analysis they choose and use this method to verify admissibility before relying on the arena.

pub fn bottom_handle(&self) -> BottomHandle<'_>

Obtain a bottom-end allocation handle.

pub fn top_handle(&self) -> TopHandle<'_>

Obtain a top-end allocation handle.

pub fn stack_handle(&self) -> BottomHandle<'_>

Alias for Arena::bottom_handle. Suitable for code that treats the bottom end as a stack-like region.

pub fn heap_handle(&self) -> TopHandle<'_>

Alias for Arena::top_handle. Suitable for code that treats the top end as a heap-like region whose allocations are reset together rather than freed individually.

pub fn alloc_bottom_bytes(&self, n: usize) -> Result<NonNull<[u8]>, AllocError>

Allocate n bytes from the bottom end with no alignment requirement. Convenience wrapper for byte buffers and similar allocations where the caller does not care about alignment.

Equivalent to allocating with a Layout::from_size_align(n, 1) through the BottomHandle Allocator implementation.

pub fn alloc_top_bytes(&self, n: usize) -> Result<NonNull<[u8]>, AllocError>

Allocate n bytes from the top end with no alignment requirement.

Trait Implementations

impl Debug for Arena

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Drop for Arena

fn drop(&mut self)

Executes the destructor for this type.