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 HEAP_START_ADDRESS. When an allocation would exceed available heap space, accessing that memory triggers a segfault, which is how Rialo signals out-of-memory conditions. This design eliminates the need for the allocator to know the heap size at compile time.

§Key Assumptions

This allocator relies on guarantees provided by the Rialo runtime:

  1. Heap location: The heap always starts at address 0x300000000
  2. Zero-initialization: The Rialo runtime zero-initializes the heap region before program execution begins
  3. Segfault on overflow: Accessing memory beyond the allocated heap causes a segfault that terminates the transaction

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 HEAP_START.

Constants§

MIN_HEAP_LENGTH
Minimum guaranteed heap size.