Struct Context 

pub struct Context { /* private fields */ }

Everything a running function can reach, other than the registry.

A context holds three things:

• a stack, which carries arguments and results between calls,
• registers, the closest thing to local variables,
• custom data, a name to value map for anything else a frontend needs to keep around.

Both stack and registers only ever move data, never copy it. A type that wants copies has to provide a function that pushes a duplicate itself.

Registers are scoped: every call saves the register count on entry and drops back down to it on exit, so a function only sees its own registers. That is what Context::store_registers and Context::restore_registers do, and crate::function::Function::invoke calls them for you.

Implementations

impl Context

pub fn new(stack_capacity: usize, registers_capacity: usize) -> Self

Allocates a context with fixed stack and register capacities, in bytes.

Both are rounded up to a power of two. Nothing grows later, so pick sizes that fit the deepest call chain the scripts will make.

pub fn fork(&self) -> Self

Builds a fresh, empty context with the same capacities as this one.

Used to give a worker thread a context of its own.

pub fn stack_capacity(&self) -> usize

Returns the stack size in bytes.

pub fn registers_capacity(&self) -> usize

Returns the register storage size in bytes.

pub fn stack(&mut self) -> &mut DataStack

Returns the value stack, where arguments and results are passed.

pub fn registers(&mut self) -> &mut DataStack

Returns the register storage.

Indices used here are absolute. Prefer Context::access_register, which counts from the current call’s barrier.

pub fn stack_and_registers(&mut self) -> (&mut DataStack, &mut DataStack)

Returns stack and registers at once, for moving values between them.

pub fn store_registers(&mut self)

Marks the current register count, so the next Context::restore_registers drops back down to it.

pub fn restore_registers(&mut self)

Drops every register defined since the matching Context::store_registers.

pub fn registers_barriers(&self) -> &[usize]

Returns the stored register counts, one per call currently on the stack.

pub fn absolute_register_index(&self, index: usize) -> usize

Turns a register index relative to the current call into an absolute one.

pub fn access_register( &mut self, index: usize, ) -> Option<DataStackRegisterAccess<'_>>

Takes a handle to one of the current call’s registers.

Returns None when the index was never defined.

pub fn custom<T: Send + Sync + 'static>(&self, name: &str) -> Option<&T>

Reads a value stored under name, or returns None when it is absent or of another type.

pub fn custom_mut<T: Send + Sync + 'static>( &mut self, name: &str, ) -> Option<&mut T>

Mutable Context::custom.

pub fn set_custom<T: Send + Sync + 'static>( &mut self, name: impl ToString, data: T, )

Stores a value under name, replacing anything already there.

This is the escape hatch for state a frontend needs but the platform does not model, for example a producer that builds a host per worker thread.