Struct Vm

use rune::{Context, Vm, Unit};
use rune::compile::ItemBuf;

use std::sync::Arc;

let context = Context::with_default_modules()?;
let context = Arc::new(context.runtime()?);

let mut sources = rune::sources! {
    entry => {
        pub fn max(a, b) {
            if a > b {
                a
            } else {
                b
            }
        }
    }
};

let unit = rune::prepare(&mut sources).build()?;
let unit = Arc::new(unit);

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

// Looking up an item from the source.
let dynamic_max = vm.lookup_function(["max"])?;

let value: i64 = rune::from_value(dynamic_max.call((10, 20)).into_result()?)?;
assert_eq!(value, 20);

// Building an item buffer to lookup an `::std` item.
let mut item = ItemBuf::with_crate("std")?;
item.push("i64")?;
item.push("max")?;

let max = vm.lookup_function(&item)?;

let value: i64 = rune::from_value(max.call((10, 20)).into_result()?)?;
assert_eq!(value, 20);

Source

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

Run the given vm to completion.

If any async instructions are encountered, this will error.

Source

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

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

Source

pub fn execute<A, N>( &mut self, name: N, args: A, ) -> Result<VmExecution<&mut Self>, VmError>
where N: ToTypeHash, 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 rune::Hash;

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

§Examples

use rune::{Context, Unit};
use std::sync::Arc;

let context = Context::with_default_modules()?;
let context = Arc::new(context.runtime()?);

// Normally the unit would be created by compiling some source,
// and since this one is empty it won't do anything.
let unit = Arc::new(Unit::default());

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

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

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

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

use rune::{Context, Unit};
use std::sync::Arc;

let context = Context::with_default_modules()?;
let context = Arc::new(context.runtime()?);

// Normally the unit would be created by compiling some source,
// and since this one is empty it won't do anything.
let unit = Arc::new(Unit::default());

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

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

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

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

Source

pub fn send_execute<A, N>( self, name: N, args: A, ) -> Result<VmSendExecution, VmError>
where N: ToTypeHash, 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.

Source

pub fn call<A, N>(&mut self, name: N, args: A) -> Result<Value, VmError>
where N: ToTypeHash, 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.

Source

pub async fn async_call<A, N>( &mut self, name: N, args: A, ) -> Result<Value, VmError>
where N: ToTypeHash, 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.

Source

pub fn with<F, T>(&mut self, f: F) -> T
where F: FnOnce() -> T,

Call the provided closure within the context of this virtual machine.

This allows for calling protocol function helpers like Value::string_display which requires access to a virtual machine.

use rune::{Context, Unit};
use rune::runtime::Formatter;
use std::sync::Arc;

let context = Context::with_default_modules()?;
let context = Arc::new(context.runtime()?);

// Normally the unit would be created by compiling some source,
// and since this one is empty it'll just error.
let unit = Arc::new(Unit::default());

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

let output = vm.call(["main"], ())?;

// Call the string_display protocol on `output`. This requires
// access to a virtual machine since it might use functions
// registered in the unit associated with it.
let mut f = Formatter::new();

// Note: We do an extra unwrap because the return value is
// `fmt::Result`.
vm.with(|| output.string_display(&mut f)).into_result()?;