rune

Struct Vm

Source
pub struct Vm { /* private fields */ }
Expand description

A stack which references variables indirectly from a slab.

Implementations§

Source§

impl Vm

Source

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

Construct a new virtual machine.

Constructing a virtual machine is a cheap constant-time operation.

See unit_mut and context_mut documentation for information on how to re-use existing Vm’s.

Source

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

Construct a new virtual machine with a custom stack.

Source

pub fn without_runtime(unit: Arc<Unit>) -> Self

Construct a vm with a default empty RuntimeContext. This is useful when the Unit was constructed with an empty Context.

Source

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.

Source

pub fn is_same_context(&self, context: &Arc<RuntimeContext>) -> bool

Test if the virtual machine is the same context.

Source

pub fn is_same_unit(&self, unit: &Arc<Unit>) -> bool

Test if the virtual machine is the same context.

Source

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

Set the current instruction pointer.

Source

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

Get the stack.

Source

pub fn stack(&self) -> &Stack

Get the stack.

Source

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

Get the stack mutably.

Source

pub fn context_mut(&mut self) -> &mut Arc<RuntimeContext>

Access the context related to the virtual machine mutably.

Note that this can be used to swap out the RuntimeContext associated with the running vm. Note that this is only necessary if the underlying Context is different or has been modified. In contrast to constructing a new vm, this allows for amortised re-use of any allocations.

After doing this, it’s important to call clear to clean up any residual state.

Source

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

Access the context related to the virtual machine.

Source

pub fn unit_mut(&mut self) -> &mut Arc<Unit>

Access the underlying unit of the virtual machine mutably.

Note that this can be used to swap out the Unit of execution in the running vm. In contrast to constructing a new vm, this allows for amortised re-use of any allocations.

After doing this, it’s important to call clear to clean up any residual state.

Source

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

Access the underlying unit of the virtual machine.

Source

pub fn ip(&self) -> usize

Access the current instruction pointer.

Source

pub fn last_ip(&self) -> usize

Access the last instruction that was executed.

Source

pub fn clear(&mut self)

Reset this virtual machine, freeing all memory used.

Source

pub fn lookup_function<N>(&self, name: N) -> Result<Function, VmError>
where N: ToTypeHash,

Look up a function in the virtual machine by its name.

§Examples
use rune::{Context, Unit, Vm};

use std::sync::Arc;

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

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

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

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

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

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

// Building an item buffer to lookup an `::std` item.
let item = rune::item!(::std::i64::max);
let max = vm.lookup_function(item)?;

let value = max.call::<i64>((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( &mut self, name: impl ToTypeHash, args: impl Args, ) -> Result<VmExecution<&mut Self>, VmError>

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 unit = Arc::new(Unit::default());
let mut vm = rune::Vm::without_runtime(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;

// 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::without_runtime(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( self, name: impl ToTypeHash, args: impl Args + Send, ) -> Result<VmSendExecution, VmError>

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( &mut self, name: impl ToTypeHash, args: impl GuardedArgs, ) -> Result<Value, VmError>

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 fn call_with_diagnostics( &mut self, name: impl ToTypeHash, args: impl GuardedArgs, diagnostics: Option<&mut dyn VmDiagnostics>, ) -> Result<Value, VmError>

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>(&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::display_fmt which requires access to a virtual machine.

use rune::{Value, Vm};
use rune::runtime::{Formatter, VmError};

fn use_with(vm: &Vm, output: &Value, f: &mut Formatter) -> Result<(), VmError> {
    vm.with(|| output.display_fmt(f)).into_result()?;
    Ok(())
}

Trait Implementations§

Source§

impl AsMut<Vm> for Vm

Source§

fn as_mut(&mut self) -> &mut Vm

Converts this type into a mutable reference of the (usually inferred) input type.
Source§

impl AsRef<Vm> for Vm

Source§

fn as_ref(&self) -> &Vm

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

impl Debug for Vm

Source§

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

Formats the value using the given formatter. Read more
Source§

impl TryClone for Vm

Source§

fn try_clone(&self) -> Result<Self>

Try to clone the current value, raising an allocation error if it’s unsuccessful.
Source§

fn try_clone_from(&mut self, source: &Self) -> Result<(), Error>

Performs copy-assignment from source. Read more

Auto Trait Implementations§

§

impl Freeze for Vm

§

impl !RefUnwindSafe for Vm

§

impl !Send for Vm

§

impl !Sync for Vm

§

impl Unpin for Vm

§

impl !UnwindSafe for Vm

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T> Instrument for T

Source§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
Source§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
Source§

impl<T> TryToOwned for T
where T: TryClone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn try_to_owned(&self) -> Result<T, Error>

Creates owned data from borrowed data, usually by cloning. Read more
Source§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

Source§

fn vzip(self) -> V

Source§

impl<T> WithSubscriber for T

Source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
Source§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more
Source§

impl<T> ErasedDestructor for T
where T: 'static,

Source§

impl<T> MaybeSendSync for T