Struct Program 

pub struct Program { /* private fields */ }

A compiled candela program with resident interpreter state.

Registers and heap pools persist between Program::call invocations, so state established by one call (including anything a host function mutates on the Rust side) is visible to the next.

Program is single-threaded (!Send/!Sync): it holds Rc dispatchers and reflects candela’s single-threaded VM.

Implementations

impl Program

pub fn warnings(&self) -> &[Diagnostic]

The warnings compiling this program raised, in the order they were raised. A warning does not stop the compile; see the warnings section of the error reference for what each one means.

pub fn call( &mut self, fn_name: &str, args: &[Value], ) -> Result<Value, Diagnostic>

Invokes the script-defined function fn_name with args, returning its value (or Value::Null for a void function).

The first call with a given set of argument types compiles a small trampoline (which specializes fn_name for those types if it hasn’t been already) onto the resident instruction stream; later calls with the same types run it again. It runs against the persistent register/heap state, so globals mutated by a previous call remain visible.

A diagnostic raised while compiling the trampoline leaves the resident tables exactly as they stood before this call began, and the Program stays callable afterward.

Errors

Returns a Diagnostic if fn_name is unknown, if the arguments don’t type-check against its signature, or if the call raises a runtime error.

pub fn collect(&mut self, budget: u32) -> bool

Does up to about budget units of garbage collection while the program is idle, and answers whether no collection work is left.

Call it between calls into the program, where the host would otherwise wait, such as between frames. It carries on a collection already under way, or begins one when the heap has grown enough since the last; on a heap that has not, it does nothing and answers true. A unit is about one object traced or one freed slot, never a length of time, so the same calls do the same work on every machine. collect(u32::MAX) runs a whole collection. Beginning a collection reads every root at once whatever the budget.

Once a host has called this, allocations leave more of the work to it and begin a collection themselves only when the heap has grown further.

pub fn gc_stats(&self) -> GcStats

What the collector has done over this program’s heap, and how large the heap is. See GcStats.