Struct Caller

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

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 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 of ExternRefs.

Same as Store::gc.

pub fn fuel_consumed(&self) -> Option<u64>

Returns the fuel consumed by this store.

For more information see Store::fuel_consumed

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

Inject more fuel into this store to be consumed when executing wasm code.

For more information see Store::add_fuel

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

Synthetically consumes fuel from the store.

For more information see Store::consume_fuel

pub fn out_of_fuel_trap(&mut self)

Configures this Store to trap whenever fuel runs out.

For more information see Store::out_of_fuel_trap

pub fn out_of_fuel_async_yield( &mut self, injection_count: u64, fuel_to_inject: u64, )

Configures this Store to yield while executing futures whenever fuel runs out.

For more information see Store::out_of_fuel_async_yield

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.