Struct Vm 

pub struct Vm { /* private fields */ }

Virtual machine for EndBASIC program execution.

Implementations

impl Vm

pub fn new(upcalls_by_name: HashMap<SymbolKey, Rc<dyn Callable>>) -> Self

Creates a new VM with the given upcalls_by_name as the available built-in callables.

pub fn new_with_limits( upcalls_by_name: HashMap<SymbolKey, Rc<dyn Callable>>, limits: Limits, ) -> Self

Creates a new VM with the given upcalls_by_name and resource limits.

pub fn reset(&mut self)

Resets any existing execution state, including upcall caches and the program counter.

pub fn clear(&mut self)

Resets runtime state (registers, heap, last error, call stack, program counter) but preserves upcall caches so the same image can continue to be executed.

Note: because the program counter is also reset, callers need to either re-set it to a specific location or replace the image with one that resumes from the start.

pub fn clear_error_handler(&mut self)

Clears the current error handler without affecting execution state or captured errors.

pub fn get_global( &self, image: &Image, key: &SymbolKey, ) -> GetGlobalResult<Option<ConstantDatum>>

Returns the value of the global scalar variable key as a ConstantDatum.

Returns Ok(None) if the variable is not defined (no image is loaded or the variable was not declared). Returns Err if the variable exists but is an array; in that case, use get_global_array instead.

pub fn get_global_array( &self, image: &Image, key: &SymbolKey, subscripts: &[i32], ) -> GetGlobalResult<Option<ConstantDatum>>

Returns the value of an element in the global array variable key at the given subscripts as a ConstantDatum.

Returns Ok(None) if the variable is not defined (no image is loaded or the variable was not declared). Returns Err if the variable exists but is a scalar (use get_global instead), or if the subscripts are out of bounds.

pub fn get_program( &self, image: &Image, key: &SymbolKey, ) -> GetGlobalResult<Option<ConstantDatum>>

Returns the value of the program-scope scalar variable key as a ConstantDatum.

Returns Ok(None) if the variable is not defined (no image is loaded or the variable was not declared). Returns Err if the variable exists but is an array; in that case, use get_program_array instead.

pub fn get_program_array( &self, image: &Image, key: &SymbolKey, subscripts: &[i32], ) -> GetGlobalResult<Option<ConstantDatum>>

Returns the value of an element in the program-scope array variable key at the given subscripts as a ConstantDatum.

Returns Ok(None) if the variable is not defined (no image is loaded or the variable was not declared). Returns Err if the variable exists but is a scalar (use get_program instead), or if the subscripts are out of bounds.

pub fn exec<'a>(&'a mut self, image: &'a Image) -> StopReason<'a>

Starts or resumes execution of image.

Returns a StopReason indicating why execution stopped, which may be due to program termination, an exception, or a pending upcall that requires caller handling.

pub fn interrupt(&mut self, image: &Image)

Stops execution of image so that the next call to exec starts at EOF.

This is useful when external events interrupt execution and the caller wants to avoid resuming a partially-run image by mistake.