Struct runestick::Vm

pub struct Vm { /* fields omitted */ }

A stack which references variables indirectly from a slab.

Implementations

impl Vm

pub const fn new(context: Arc<RuntimeContext>, unit: Arc<Unit>) -> Self

Construct a new runestick virtual machine.

pub const fn new_with_stack(
    context: Arc<RuntimeContext>,
    unit: Arc<Unit>,
    stack: Stack
) -> Self

Construct a new runestick virtual machine.

pub fn complete(self) -> Result<Value, VmError>

Run the given vm to completion.

If any async instructions are encountered, this will error.

pub async fn async_complete(self) -> Result<Value, VmError>

Run the given vm to completion with support for async functions.

pub fn is_same(&self, context: &Arc<RuntimeContext>, unit: &Arc<Unit>) -> bool

Test if the virtual machine is the same context and unit as specified.

pub fn set_ip(&mut self, ip: usize)

Set the current instruction pointer.

pub fn call_frames(&self) -> &[CallFrame]

Get the stack.

pub fn stack(&self) -> &Stack

Get the stack.

pub fn stack_mut(&mut self) -> &mut Stack

Get the stack mutably.

pub fn context(&self) -> &Arc<RuntimeContext>

Access the context related to the virtual machine.

pub fn unit(&self) -> &Arc<Unit>

Access the underlying unit of the virtual machine.

pub fn ip(&self) -> usize

Access the current instruction pointer.

pub fn clear(&mut self)

Reset this virtual machine, freeing all memory used.

pub fn modify_ip(&mut self, offset: isize) -> Result<(), VmError>

Modify the current instruction pointer.

pub fn execute<A, N>(self, name: N, args: A) -> Result<VmExecution, VmError> where
    N: IntoTypeHash,
    A: Args, 

Call the function identified by the given name.

Computing the function hash from the name can be a bit costly, so it’s worth noting that it can be precalculated:

use runestick::{Hash, Item};

let name = Hash::type_hash(&["main"]);

Examples

use runestick::{Context, Unit, FromValue, Source};
use std::sync::Arc;

fn main() -> runestick::Result<()> {
    let context = Context::with_default_modules()?;
    let context = Arc::new(context.runtime());
    let unit = Arc::new(Unit::default());
    // Normally the unit would be created by compiling some source,
    // and since this one is empty it won't do anything.

    let vm = runestick::Vm::new(context, unit);

    let output = vm.execute(&["main"], (33i64,))?.complete()?;
    let output = i64::from_value(output)?;

    println!("output: {}", output);
    Ok(())
}

You can use a Vec<Value> to provide a variadic collection of arguments.

use runestick::{Context, Unit, FromValue, Source, ToValue};
use std::sync::Arc;

fn main() -> runestick::Result<()> {
    let context = Context::with_default_modules()?;
    let context = Arc::new(context.runtime());
    let unit = Arc::new(Unit::default());
    // Normally the unit would be created by compiling some source,
    // and since this one is empty it won't do anything.

    let vm = runestick::Vm::new(context, unit);

    let mut args = Vec::new();
    args.push(1u32.to_value()?);
    args.push(String::from("Hello World").to_value()?);

    let output = vm.execute(&["main"], args)?.complete()?;
    let output = i64::from_value(output)?;

    println!("output: {}", output);
    Ok(())
}

pub fn send_execute<A, N>(
    self,
    name: N,
    args: A
) -> Result<VmSendExecution, VmError> where
    N: IntoTypeHash,
    A: Send + Args, 

An execute variant that returns an execution which implements Send, allowing it to be sent and executed on a different thread.

This is accomplished by preventing values escaping from being non-exclusively sent with the execution or escaping the execution. We only support encoding arguments which themselves are Send.

pub fn call<A, N>(self, name: N, args: A) -> Result<Value, VmError> where
    N: IntoTypeHash,
    A: GuardedArgs, 

Call the given function immediately, returning the produced value.

This function permits for using references since it doesn’t defer its execution.

Panics

If any of the arguments passed in are references, and that references is captured somewhere in the call as Mut<T> or Ref<T> this call will panic as we are trying to free the metadata relatedc to the reference.

pub async fn async_call<A, N>(self, name: N, args: A) -> Result<Value, VmError> where
    N: IntoTypeHash,
    A: GuardedArgs, 

Call the given function immediately asynchronously, returning the produced value.

This function permits for using references since it doesn’t defer its execution.

Panics

If any of the arguments passed in are references, and that references is captured somewhere in the call as Mut<T> or Ref<T> this call will panic as we are trying to free the metadata relatedc to the reference.

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.