Struct muse_lang::vm::VmContext

pub struct VmContext<'a, 'guard> { /* private fields */ }

A virtual machine execution context.

While a VmContext is held and not executing code, the garbage collector cannot run and the virtual machine is exclusivly accessible by the current thread.

Implementations

impl<'context, 'guard> VmContext<'context, 'guard>

pub fn new( vm: &'context Vm, guard: &'context mut CollectionGuard<'guard>, ) -> Self

Returns a new execution context for vm using guard.

pub fn guard_mut(&mut self) -> &mut CollectionGuard<'guard>

Returns an exclusive reference to the collection guard.

pub fn guard(&self) -> &CollectionGuard<'guard>

Returns a reference to the collection guard.

pub fn vm(&mut self) -> &mut VmState

Returns a reference to the virtual machine.

pub fn cloned_vm(&self) -> Vm

Returns a new virtual machine with the same modules and registered code.

All registers, stack values, and stack frames will be empty on the new Vm.

pub fn caller_access_level(&self, module: &Dynamic<Module>) -> Access

Returns the access to allow the caller of the current function.

pub fn while_unlocked<R>( &mut self, func: impl FnOnce(&mut CollectionGuard<'_>) -> R, ) -> R

Executes func while the virtual machine is unlocked.

This can be used in combination with [CollectionGuard::while_unlocked] to perform code while the garbage collector is free to execute.

pub fn prepare(&mut self, code: &Code) -> 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 execute(&mut self, code: &Code) -> Result<Value, ExecutionError>

Executes code and returns the result.

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

Executes code for at most duration before returning a timout.

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

Executes code for until instant before returning a timout.

pub fn resume(&mut self) -> 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, ) -> 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, ) -> 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<'vm>( &'vm mut self, code: &Code, ) -> Result<ExecuteAsync<'vm, 'context, 'guard>, ExecutionError>

Returns a future that executes code asynchronously.

pub fn resume_async<'vm>(&'vm mut self) -> ExecuteAsync<'vm, '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<'vm>( &'vm mut self, duration: Duration, ) -> ExecuteAsync<'vm, '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<'vm>( &'vm mut self, instant: Instant, ) -> ExecuteAsync<'vm, '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(&mut self, amount: usize)

Increases the current budget by amount.

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

pub fn prepare_call( &mut self, function: &Rooted<Function>, arity: Arity, ) -> 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 invoke( &mut self, name: impl Into<SymbolRef>, params: impl InvokeArgs, ) -> Result<Value, ExecutionError>

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

pub fn waker(&self) -> &Waker

Returns a waker that will wake this virtual machine context when waiting on async tasks.

pub fn declare_variable( &mut self, name: SymbolRef, mutable: bool, ) -> 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( &mut self, name: impl Into<SymbolRef>, value: Value, ) -> Result<Option<Value>, Fault>

Declares an immutable variable with name containing value.

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

Declares an mutable variable with name containing value.

pub fn declare_function( &mut self, function: Function, ) -> 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.

pub fn resolve(&mut self, name: &Symbol) -> Result<Value, Fault>

Resolves the value at path.

pub fn allocate(&mut self, count: usize) -> Result<Stack, Fault>

Allocates count entries on the stack. Returns the first allocated index.

pub fn current_code(&self) -> Option<&Code>

Returns a reference to the currently executing code.

pub fn current_instruction(&self) -> usize

Returns the instruction offset in the current frame.

pub fn current_frame(&self) -> &[Value]

Returns a slice of the current stack frame.

pub fn current_frame_mut(&mut self) -> &mut [Value]

Returns an exclusive reference to the slice of the current stack frame.

pub fn current_frame_size(&self) -> usize

Returns the size of the current stack frame.

pub fn reset(&mut self)

Resets the stack and registers to their initial state and clears any executing code.

All declarations and modules will still be loaded in the virtual machine.

pub fn backtrace(&self) -> Vec<StackFrame>

Generates a backtrace for the current virtual machine state.

Methods from Deref<Target = VmState>

pub fn set_steps_per_charge(&mut 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 registers(&self) -> &[Value; 256]

Returns a slice of the registers.

pub fn registers_mut(&mut self) -> &mut [Value; 256]

Returns exclusive access to the registers.

pub fn current_module(&self) -> ModuleId

Returns the id of the module that owns the code currently executing.

pub fn root_module(&self) -> Dynamic<Module>

Returns the root module for this virtual machine.

Trait Implementations

impl<'guard> AsRef<CollectionGuard<'guard>> for VmContext<'_, 'guard>

fn as_ref(&self) -> &CollectionGuard<'guard>

Converts this type into a shared reference of the (usually inferred) input type.

impl Deref for VmContext<'_, '_>

type Target = VmState

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl DerefMut for VmContext<'_, '_>

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.