wiggle::wasmtime_crate

Struct Caller

pub struct Caller<'a, T> { /* private fields */ }
Expand description

A structure representing the caller’s context when creating a function via Func::wrap.

This structure can be taken as the first parameter of a closure passed to Func::wrap or other constructors, and serves two purposes:

  • First consumers can use Caller<'_, T> to get access to StoreContextMut<'_, T> and/or get access to T itself. This means that the Caller type can serve as a proxy to the original Store itself and is used to satisfy AsContext and AsContextMut bounds.

  • Second a Caller can be used as the name implies, learning about the caller’s context, namely it’s exported memory and exported functions. This allows functions which take pointers as arguments to easily read the memory the pointers point into, or if a function is expected to call malloc in the wasm module to reserve space for the output you can do that.

Host functions which want access to Store-level state are recommended to use this type.

Implementations§

§

impl<T> Caller<'_, T>

pub fn get_export(&mut self, name: &str) -> Option<Extern>

Looks up an export from the caller’s module by the name given.

This is a low-level function that’s typically used to implement passing of pointers or indices between core Wasm instances, where the callee needs to consult the caller’s exports to perform memory management and resolve the references.

For comparison, in components, the component model handles translating arguments from one component instance to another and managing memory, so that callees don’t need to be aware of their callers, which promotes virtualizability of APIs.

§Return

If an export with the name provided was found, then it is returned as an Extern. There are a number of situations, however, where the export may not be available:

  • The caller instance may not have an export named name
  • There may not be a caller available, for example if Func was called directly from host code.

It’s recommended to take care when calling this API and gracefully handling a None return value.

pub fn get_module_export(&mut self, export: &ModuleExport) -> Option<Extern>

Looks up an exported Extern value by a ModuleExport value.

This is similar to Self::get_export but uses a ModuleExport value to avoid string lookups where possible. ModuleExports can be obtained by calling Module::get_export_index on the Module that an instance was instantiated with.

This method will search the module for an export with a matching entity index and return the value, if found.

Returns None if there was no export with a matching entity index.

§Panics

Panics if store does not own this instance.

§Usage
use std::str;


let module = Module::new(
    store.engine(),
    r#"
        (module
            (import "" "" (func $log_str (param i32 i32)))
            (func (export "foo")
                i32.const 4   ;; ptr
                i32.const 13  ;; len
                call $log_str)
            (memory (export "memory") 1)
            (data (i32.const 4) "Hello, world!"))
    "#,
)?;

let Some(module_export) = module.get_export_index("memory") else {
   anyhow::bail!("failed to find `memory` export in module");
};

let log_str = Func::wrap(&mut store, move |mut caller: Caller<'_, ()>, ptr: i32, len: i32| {
    let mem = match caller.get_module_export(&module_export) {
        Some(Extern::Memory(mem)) => mem,
        _ => anyhow::bail!("failed to find host memory"),
    };
    let data = mem.data(&caller)
        .get(ptr as u32 as usize..)
        .and_then(|arr| arr.get(..len as u32 as usize));
    let string = match data {
        Some(data) => match str::from_utf8(data) {
            Ok(s) => s,
            Err(_) => anyhow::bail!("invalid utf-8"),
        },
        None => anyhow::bail!("pointer/length out of bounds"),
    };
    assert_eq!(string, "Hello, world!");
    println!("{}", string);
    Ok(())
});
let instance = Instance::new(&mut store, &module, &[log_str.into()])?;
let foo = instance.get_typed_func::<(), ()>(&mut store, "foo")?;
foo.call(&mut store, ())?;

pub fn data(&self) -> &T

Access the underlying data owned by this Store.

Same as Store::data

pub fn data_mut(&mut self) -> &mut T

Access the underlying data owned by this Store.

Same as Store::data_mut

pub fn engine(&self) -> &Engine

Returns the underlying Engine this store is connected to.

pub fn gc(&mut self)

Perform garbage collection.

Same as Store::gc.

pub async fn gc_async(&mut self)
where T: Send,

Perform garbage collection asynchronously.

Same as Store::gc_async.

pub fn get_fuel(&self) -> Result<u64, Error>

Returns the remaining fuel in the store.

For more information see Store::get_fuel

pub fn set_fuel(&mut self, fuel: u64) -> Result<(), Error>

Set the amount of fuel in this store to be consumed when executing wasm code.

For more information see Store::set_fuel

pub fn fuel_async_yield_interval( &mut self, interval: Option<u64>, ) -> Result<(), Error>

Configures this Store to yield while executing futures every N units of fuel.

For more information see Store::fuel_async_yield_interval

Trait Implementations§

§

impl<T> AsContext for Caller<'_, T>

§

type Data = T

The host information associated with the Store, aka the T in Store<T>.
§

fn as_context(&self) -> StoreContext<'_, T>

Returns the store context that this type provides access to.
§

impl<T> AsContextMut for Caller<'_, T>

§

fn as_context_mut(&mut self) -> StoreContextMut<'_, T>

Returns the store context that this type provides access to.

Auto Trait Implementations§

§

impl<'a, T> Freeze for Caller<'a, T>

§

impl<'a, T> !RefUnwindSafe for Caller<'a, T>

§

impl<'a, T> Send for Caller<'a, T>
where T: Send,

§

impl<'a, T> Sync for Caller<'a, T>
where T: Sync,

§

impl<'a, T> Unpin for Caller<'a, T>

§

impl<'a, T> !UnwindSafe for Caller<'a, T>

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> IntoEither for T

Source§

fn into_either(self, into_left: bool) -> Either<Self, Self>

Converts self into a Left variant of Either<Self, Self> if into_left is true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
Source§

fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
where F: FnOnce(&Self) -> bool,

Converts self into a Left variant of Either<Self, Self> if into_left(&self) returns true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
§

impl<T> Pointable for T

§

const ALIGN: usize = _

The alignment of pointer.
§

type Init = T

The type for initializers.
§

unsafe fn init(init: <T as Pointable>::Init) -> usize

Initializes a with the given initializer. Read more
§

unsafe fn deref<'a>(ptr: usize) -> &'a T

Dereferences the given pointer. Read more
§

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

Mutably dereferences the given pointer. Read more
§

unsafe fn drop(ptr: usize)

Drops the object pointed to by the given pointer. Read more
Source§

impl<T> Pointee for T

Source§

type Pointer = u32

Source§

fn debug( pointer: <T as Pointee>::Pointer, f: &mut Formatter<'_>, ) -> Result<(), Error>

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> 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