Skip to main content

Module allocator

rialo_s_program_entrypoint

Module allocator 

Source
Expand description

Custom heap allocator for Rialo programs that supports dynamic heap sizes.

§Overview

This module provides a bump allocator optimized for Rialo’s execution model. Unlike the default allocator which assumes a fixed 32KB heap, this implementation automatically utilizes whatever heap size is allocated by the runtime, including custom sizes requested via Compute Budget instructions.

§How It Works

The allocator stores a small header (4-8 bytes) at the start of the heap containing:

  • Current allocation offset
  • Optional global state (via generic parameter G)

Memory is allocated by growing upward from the heap base. The loader supplies the usable heap size at runtime (set_heap_limit); an allocation that would exceed it is refused and surfaces as a clean allocation error (handle_alloc_error), so the allocator never needs the heap size at compile time. Writing past the heap is only possible by bypassing this allocator, in which case accessing memory beyond the mapped region eventually traps.

§Key Assumptions

This allocator relies on guarantees provided by the Rialo runtime:

  1. Heap location: On RISC-V the loader supplies the heap base at runtime (recorded via set_heap_base, called from the entrypoint before any allocation); on other targets it is the fixed address 0x300000000.
  2. Zero-initialization: The Rialo runtime zero-initializes the heap region before program execution begins
  3. Bounded allocation: On RISC-V the loader also supplies the usable heap size (recorded via set_heap_limit); allocations beyond it are refused. Accessing memory beyond the mapped region, only reachable by bypassing this allocator, still traps.

These assumptions are part of Rialo’s documented runtime behavior and are validated in tests using a simulated heap environment.

§Deallocation Behavior

As a bump allocator, this implementation:

  • Can reclaim space from the most recent allocation if deallocated
  • Intentionally leaks memory for all other deallocations (by design)
  • Is optimized for Rialo’s short-lived transaction model where all memory is reclaimed when the transaction completes

§Usage

The allocator is typically set up via the custom_heap_default! macro in the entrypoint crate. Programs don’t interact with it directly - it’s used automatically by Rust’s allocation APIs (Vec, Box, etc.).

Structs§

BumpAllocator
Bump allocator that grows upward from the heap base.

Constants§

MIN_HEAP_LENGTH
Minimum guaranteed heap size.