ArenaUsage

ArenaUsage()

Metadata for a memory arena.

Provisional: importable, but outside the compatibility promise; a minor release can change or remove it.

memory: MemoryType = Field(..., description='Runtime memory of the arena.')

Runtime (kernel-visible) memory of the arena.

total_size: int = Field(default=0, description='Total bytes in this arena')

Total bytes in this arena.

used: int = Field(default=0, description='Bytes actually used')

Bytes actually used. For bump-allocated arenas (constant, persistent) this equals total_size.

role: ArenaRole = Field(default=ArenaRole.SCRATCH, description='Logical role of the arena (scratch | persistent | constant).')

Logical role of the arena.

source_memory: MemoryType = Field(default=None, description="Cold-storage source memory for the arena's contents. Equals ``memory`` for scratch, persistent, and cold constant arenas; differs from ``memory`` for staged constant arenas where bytes are copied at boot from this source memory into the writable runtime arena. Defaults to None for backward compatibility with callers that construct ArenaUsage directly; the bundled GreedyPlanner always populates it.")

The cold-storage memory the arena’s contents are sourced from. For scratch and persistent arenas this equals memory (purely runtime, no source blob). For constant arenas it equals memory in the cold case (arena buffer is the cold blob in place) and differs from memory in the staged case (arena buffer is a writable runtime copy of a source blob in source_memory).

alignment: int = Field(default=16, description='Resolved alignment of the arena base symbol (and floor for slot offsets within it). Stamped by the planner from max(implementation floor, platform.min_alignment, MemoryConstraint.arena_alignment).')

is_staged: bool

True iff this arena has a distinct cold source memory.

Equivalent to source_memory is not None and source_memory != memory. Centralizes the cold-vs-staged predicate so templates and handlers do not duplicate it.

For scratch and persistent arenas this is always False (they have no cold source). For constant arenas it distinguishes the two emit shapes:

False (cold): the arena buffer itself is a static const blob in cold storage.
True (staged): the arena buffer is a writable runtime copy hydrated from a separate source blob in source_memory.

allocate(size: int) -> int

Allocate a segment of the arena and return its offset