class Lapis::Core::FrameArena

Overview

Linear pointer-bump frame scratchpad allocator reset once per tick.

All hot-path allocation methods (#alloc_bytes, #alloc_slice, #alloc_ptr, #push, #copy_slice, #copy_array, #mark, #rewind, #reset!, #tick!) execute with strictly ZERO GC heap allocations.

Defined in:

lapis/core/frame_arena.cr

Constant Summary

DEFAULT_ALIGNMENT = 8
DEFAULT_CAPACITY = 1048576

Constructors

Class Method Summary

Instance Method Summary

Instance methods inherited from class Object

try?(&)
try? try?

Constructor Detail

def self.configure(capacity : Int32 = DEFAULT_CAPACITY) : FrameArena #

Replaces or reconfigures the default frame arena with the given byte capacity.


def self.current : FrameArena #

Returns the default active frame arena instance.


def self.frame(&) : FrameArena #

Executes a block with the default frame arena and automatically calls #tick! on completion.


def self.new(capacity : Int32 = DEFAULT_CAPACITY) #

def self.reset! : FrameArena #

Resets the default frame arena offset to zero without advancing the frame counter.


def self.scope(&) : FrameArena #

Executes a scoped checkpoint block on the default frame arena, rewinding the bump pointer on exit.


def self.tick! : FrameArena #

Resets the default frame arena for a new engine tick, incrementing its frame counter.


Class Method Detail

def self.align_up(offset : Int32, alignment : Int32 = DEFAULT_ALIGNMENT) : Int32 #

Aligns #offset upward to the nearest multiple of alignment.


def self.alloc_slice(type : T.class, count : Int32, *, alignment : Int32 = DEFAULT_ALIGNMENT) : Slice(T) forall T #

Allocates a typed slice from the default frame arena.


def self.buffer(type : T.class, capacity : Int32, alignment : Int32 = DEFAULT_ALIGNMENT) : ArenaBuffer(T) forall T #

Allocates an appendable ArenaBuffer(T) from the default frame arena.


Instance Method Detail

def alloc_bytes(size : Int32, alignment : Int32 = DEFAULT_ALIGNMENT) : Bytes #

Carves a contiguous Bytes slice of size bytes aligned to alignment. Returns Bytes.empty and increments #overflow_count if capacity is exceeded.


def alloc_ptr(type : T.class, count : Int32 = 1, alignment : Int32 = DEFAULT_ALIGNMENT) : Pointer(T) forall T #

Carves space for count elements of T and returns a typed Pointer(T) (or Pointer(T).null if capacity is exceeded).


def alloc_slice(type : T.class, count : Int32, value : T, *, alignment : Int32 = DEFAULT_ALIGNMENT) : Slice(T) forall T #

Carves a contiguous Slice(T) of count elements and initializes every slot to value.


def alloc_slice(type : T.class, count : Int32, *, alignment : Int32 = DEFAULT_ALIGNMENT) : Slice(T) forall T #

Carves a contiguous Slice(T) of count elements from the linear scratchpad. Returns Slice(T).empty if count <= 0 or capacity is exceeded.


def allocation_count : Int32 #

def buffer(type : T.class, capacity : Int32, alignment : Int32 = DEFAULT_ALIGNMENT) : ArenaBuffer(T) forall T #

Carves an appendable ArenaBuffer(T) with fixed #capacity from the frame arena.


def bytes_remaining : Int32 #

Alias for #remaining.


def bytes_used : Int32 #

Alias for #used.


def can_allocate?(size : Int32, alignment : Int32 = DEFAULT_ALIGNMENT) : Bool #

Checks whether size bytes with alignment can fit in the remaining capacity.


def capacity : Int32 #

def clear! : self #

Alias for #reset!.


def copy_array(src : Array(T), alignment : Int32 = DEFAULT_ALIGNMENT) : Slice(T) forall T #

Copies an Array(T) into the frame arena and returns the arena-backed Slice(T).


def copy_slice(src : Slice(T), alignment : Int32 = DEFAULT_ALIGNMENT) : Slice(T) forall T #

Copies a Slice(T) into the frame arena and returns the arena-backed Slice(T).


def empty? : Bool #

Returns true if no bytes are currently allocated in this frame.


def frame_count : UInt64 #

def high_water_mark : Int32 #

def mark : Int32 #

Returns the current bump pointer offset for later #rewind.


def offset : Int32 #

def overflow_count : UInt64 #

def peak_bytes : Int32 #

Alias for #high_water_mark.


def push(value : T, alignment : Int32 = DEFAULT_ALIGNMENT) : Pointer(T) forall T #

Writes a single value T into the arena and returns a Pointer(T) to its slot.


def remaining : Int32 #

Bytes remaining before the arena reaches capacity.


def reset! : self #

Resets the linear scratchpad offset and per-frame allocation counter in O(1) time.


def reset_stats! : self #

Resets both the active bump pointer and all historical telemetry counters.


def rewind(mark_offset : Int32) : self #

Rewinds the bump pointer to a previous mark_offset within [0, @offset].


def scope(&) : self #

Executes a nested block and rewinds the arena bump pointer back to its pre-block mark.


def stats : FrameArenaStats #

Captures a value-struct telemetry snapshot of this arena.


def tick : self #

Alias for #tick! (scanned by the Zero-Allocation AST Linter as a hot-path tick method).


def tick! : self #

Advances the frame tick counter and resets the bump pointer to 0 in O(1) time.


def tick_count : UInt64 #

Alias for #frame_count.


def total_allocations : UInt64 #

def used : Int32 #

Bytes currently consumed in the active frame.


def utilization : Float64 #

Current frame utilization ratio (0.0..1.0).