Struct Machine 

pub struct Machine {

    pub heap: Vec<Word>,
    pub trail: Vec<u64>,
    pub cps: Vec<ChoicePoint>,
    pub areg: [Word; 16],
    pub breg: [Word; 16],
    pub k_fn: ContFn,
    pub k_env: u64,
    pub steps: u64,
    pub step_limit: u64,
    pub error: Option<RtError>,
    pub atoms: StringInterner,
    pub registry: Vec<RegistryEntry>,
    pub srcmap: Vec<SrcLoc>,
    pub files: Vec<String>,
    pub error_site: u32,
    pub query_vars: Vec<(String, usize)>,
    pub findall_stack: Vec<Vec<TermBuf>>,
    pub qbarrier: usize,
    pub solutions: Vec<RenderedSolution>,
    pub solution_limit: Option<usize>,
}

Fields

heap: Vec<Word>

trail: Vec<u64>

cps: Vec<ChoicePoint>

areg: [Word; 16]

breg: [Word; 16]

Build registers for plg_rt_put_struct (separate from areg so argument setup and term construction never clobber each other).

k_fn: ContFn

k_env: u64

steps: u64

step_limit: u64

error: Option<RtError>

atoms: StringInterner

registry: Vec<RegistryEntry>

srcmap: Vec<SrcLoc>

Source-location side-table (SPANS.md Layer 3), handed over by codegen at init. Empty for binaries built without provenance.

files: Vec<String>

file_id → filename, parallel to srcmap’s file field.

error_site: u32

site_id of the raise currently in flight (SPANS.md Layer 3). set_formal appends at file:line:col from it. NO_SITE (the default, and the value for runtime-internal/query-side raises) means no suffix — keeping those messages byte-identical to v1.

INVARIANT: a raising compiled builtin must set this to its site only around its own work and restore it after — always via ErrorSiteGuard, which makes the set/restore impossible to forget and keeps nested raises correct (each restores the caller’s site, not NO_SITE).

query_vars: Vec<(String, usize)>

Query variables in source order: (name, heap index of the cell).

findall_stack: Vec<Vec<TermBuf>>

findall/3 collector stack (a stack because findall can nest): each level accumulates relocatable copies of template instances.

qbarrier: usize

Cut barrier for ! in RUNTIME-WALKED goals (queries, metacalls). Call-like constructs set it for their inner goal; every walker continuation frame snapshots and restores it (the runtime mirror of the compiled cut_slot). Compiled ! never reads this.

solutions: Vec<RenderedSolution>

Solutions captured by the print continuation, already rendered.

solution_limit: Option<usize>

Implementations

impl Machine

pub fn new(atoms: StringInterner, registry: Vec<RegistryEntry>) -> Box<Machine>

pub fn new_var(&mut self) -> Word

Allocate a fresh unbound variable cell; returns its REF word.

pub fn frame_alloc(&mut self, n: usize) -> usize

Allocate n raw cells (a frame); returns the base index. Frames hold continuation state — they are not terms and must never be unified.

pub fn bind(&mut self, ref_idx: usize, value: Word)

Bind an unbound REF cell to a value, recording it on the trail.

pub fn deref(&self, w: Word) -> Word

Follow REF chains to the representative word. Bound chains are acyclic (we only ever bind unbound cells), so this terminates.

pub fn push_cp(&mut self, retry: ContFn, env: u64)

pub fn push_cp_at( &mut self, retry: ContFn, env: u64, trail_mark: usize, heap_mark: usize, )

Push a choice point whose backtrack restore-point is an EXPLICIT mark, captured before the current alternative bound anything — rather than the live heap/trail top. Lets a nondeterministic builtin bind a solution and still record the pre-binding state for the next alternative, without a rewind-then-rebind.

CALLER MUST GUARANTEE trail_mark <= self.trail.len() and heap_mark <= self.heap.len(). An out-of-range mark is caught only by the debug assertion below; in release it silently no-ops the backtrack truncation (Vec::truncate(n) with n > len does nothing), leaking bindings from a supposedly-undone alternative into the next.

pub fn push_catch_cp(&mut self, retry: ContFn, env: u64)

pub fn cut_to(&mut self, height: usize)

Cut: truncate the CP stack to height, but stop at a catch frame (v1 rule: catch/3 is opaque to cut — ! inside catch’s goal cannot prune the catch frame or anything below it).

pub fn rewind_to(&mut self, trail_mark: usize, heap_mark: usize)

Rewind bindings and heap to a popped choice point’s marks.

pub fn step(&mut self) -> bool

Bump the step counter; on exceeding the limit set the uncatchable resource error (v1: step limit cannot be trapped by catch/3). v1 wording, byte-for-byte (solver.rs step_limit_thrown).

pub fn registry_lookup(&self, functor: u32, arity: u32) -> Option<ContFn>

pub fn set_provenance(&mut self, srcmap: Vec<SrcLoc>, files: Vec<String>)

Install the codegen-emitted source-location side-table (SPANS.md Layer 3). Called once from plg_rt_init.

pub fn site_location(&self, site_id: u32) -> Option<(String, u32, u32)>

Resolve a site_id to (filename, line, col), or None for the NO_SITE sentinel / a binary built without provenance. Owned so the (cold) error path can mutate self.error without a borrow conflict.