Struct muse_lang::vm::Vm

pub struct Vm { /* private fields */ }

A virtual machine that executes compiled Muse Code.

Implementations

impl Vm

pub fn new(guard: &CollectionGuard<'_>) -> Self

Returns a new virtual machine.

Virtual machines are allocated within the [refuse] garbage collector. Each virtual machine acts as a “root” reference to all of the values contained within its stack and registers.

pub fn compile_and_execute<'a>( &self, source: impl Into<SourceCode<'a>>, guard: &mut CollectionGuard<'_>, ) -> Result<Value, Error>

Compiles source, executes it, and returns the result.

When building an interactive environment like a REPL, reusing a Compiler and calling execute enables the compiler to remember declarations from previous compilations.

pub fn prepare( &self, code: &Code, guard: &mut CollectionGuard<'_>, ) -> Result<(), Fault>

Prepares to execute code.

This function does not actually execute any code. A call to resume/resume_async is needed to begin executing the function call.

pub fn prepare_call( &self, function: &Rooted<Function>, arity: Arity, guard: &mut CollectionGuard<'_>, ) -> Result<(), Fault>

Prepares to execute the function body with arity arguments.

This function does not actually execute any code. A call to resume/resume_async is needed to begin executing the function call.

pub fn execute( &self, code: &Code, guard: &mut CollectionGuard<'_>, ) -> Result<Value, ExecutionError>

Executes code and returns the result.

pub fn execute_for( &self, code: &Code, duration: Duration, guard: &mut CollectionGuard<'_>, ) -> Result<Value, ExecutionError>

Executes code for at most duration before returning a timout.

pub fn execute_until( &self, code: &Code, instant: Instant, guard: &mut CollectionGuard<'_>, ) -> Result<Value, ExecutionError>

Executes code for until instant before returning a timout.

pub fn resume( &self, guard: &mut CollectionGuard<'_>, ) -> Result<Value, ExecutionError>

Resumes executing the current code.

This should only be called if an ExecutionError::Waiting, ExecutionError::NoBudget, or ExecutionError::Timeout was returned when executing code.

pub fn resume_until( &mut self, instant: Instant, guard: &mut CollectionGuard<'_>, ) -> Result<Value, ExecutionError>

Resumes executing the currently executing code until instant.

This should only be called if an ExecutionError::Waiting, ExecutionError::NoBudget, or ExecutionError::Timeout was returned when executing code.

pub fn resume_for( &mut self, duration: Duration, guard: &mut CollectionGuard<'_>, ) -> Result<Value, ExecutionError>

Resumes executing the currently executing code until duration as elapsed.

This should only be called if an ExecutionError::Waiting, ExecutionError::NoBudget, or ExecutionError::Timeout was returned when executing code.

pub fn execute_async<'context, 'guard>( &'context self, code: &Code, guard: &'context mut CollectionGuard<'guard>, ) -> Result<ExecuteAsync<'static, 'context, 'guard>, Fault>

Returns a future that executes code asynchronously.

pub fn resume_async<'context, 'guard>( &'context self, guard: &'context mut CollectionGuard<'guard>, ) -> ExecuteAsync<'static, 'context, 'guard>

Resumes executing the current code asynchronously.

This should only be called if an ExecutionError::Waiting, ExecutionError::NoBudget, or ExecutionError::Timeout was returned when executing code.

pub fn resume_for_async<'context, 'guard>( &'context self, duration: Duration, guard: &'context mut CollectionGuard<'guard>, ) -> ExecuteAsync<'static, 'context, 'guard>

Resumes executing the currently executing code until duration as elapsed.

This should only be called if an ExecutionError::Waiting, ExecutionError::NoBudget, or ExecutionError::Timeout was returned when executing code.

pub fn resume_until_async<'context, 'guard>( &'context self, instant: Instant, guard: &'context mut CollectionGuard<'guard>, ) -> ExecuteAsync<'static, 'context, 'guard>

Resumes executing the currently executing code until instant.

This should only be called if an ExecutionError::Waiting, ExecutionError::NoBudget, or ExecutionError::Timeout was returned when executing code.

pub fn increase_budget(&self, amount: usize)

Increases the current budget by amount.

If the virtual machine currently is unbudgeted, calling this function enables budgeting.

pub fn invoke( &self, name: impl Into<SymbolRef>, params: impl InvokeArgs, guard: &mut CollectionGuard<'_>, ) -> Result<Value, ExecutionError>

Invokes a public function at path name with the given parameters.

pub fn context<'context, 'guard>( &'context self, guard: &'context mut CollectionGuard<'guard>, ) -> VmContext<'context, 'guard>

Returns an execution context that synchronizes with the garbage collector.

pub fn set_steps_per_charge(&self, steps: u16)

Sets the number of virtual machine steps to take per budget being charged.

This also affects how often the virtual machine checks if it should yield to the garbage collector.

pub fn register(&self, register: Register) -> Value

Returns the value contained in register.

pub fn set_register(&self, register: Register, value: Value) -> Value

Replaces the current value in register with value.

pub fn stack(&self, index: Stack) -> Value

Returns the value contained at index on the stack.

Panics

This function panics if index is out of bounds of the stack.

pub fn set_stack(&self, index: Stack, value: Value) -> Value

Replaces the current value at index on the stack with value.

Panics

This function panics if index is out of bounds of the stack.

pub fn declare_variable( &self, name: SymbolRef, mutable: bool, guard: &mut CollectionGuard<'_>, ) -> Result<Stack, Fault>

Allocates a variable declaration.

Returns a stack index that has been allocated. The Muse virtual machine ensures the stack is Nil-initialized.

pub fn declare( &self, name: impl Into<SymbolRef>, value: Value, guard: &mut CollectionGuard<'_>, ) -> Result<Option<Value>, Fault>

Declares an immutable variable with name containing value.

pub fn declare_mut( &self, name: impl Into<SymbolRef>, value: Value, guard: &mut CollectionGuard<'_>, ) -> Result<Option<Value>, Fault>

Declares an mutable variable with name containing value.

pub fn declare_function( &self, function: Function, guard: &mut CollectionGuard<'_>, ) -> Result<Option<Value>, Fault>

Declares a compiled function.

Returns a reference to the function, or None if the function could not be declared because it has no name.

Trait Implementations

impl Clone for Vm

fn clone(&self) -> Vm

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Vm

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.