Crate soroban_wasmi

Expand description

The Wasmi virtual machine definitions.

These closely mirror the WebAssembly specification definitions. The overall structure is heavily inspired by the wasmtime virtual machine architecture.

§Example

The following example shows a “Hello, World!”-like example of creating a Wasm module from some initial .wat contents, defining a simple host function and calling the exported Wasm function.

The example was inspired by Wasmtime’s API example.

use anyhow::{anyhow, Result};
use wasmi::*;

fn main() -> Result<()> {
    // First step is to create the Wasm execution engine with some config.
    // In this example we are using the default configuration.
    let engine = Engine::default();
    let wat = r#"
        (module
            (import "host" "hello" (func $host_hello (param i32)))
            (func (export "hello")
                (call $host_hello (i32.const 3))
            )
        )
    "#;
    // Wasmi does not yet support parsing `.wat` so we have to convert
    // out `.wat` into `.wasm` before we compile and validate it.
    let wasm = wat::parse_str(&wat)?;
    let module = Module::new(&engine, &mut &wasm[..])?;

    // All Wasm objects operate within the context of a `Store`.
    // Each `Store` has a type parameter to store host-specific data,
    // which in this case we are using `42` for.
    type HostState = u32;
    let mut store = Store::new(&engine, 42);
    let host_hello = Func::wrap(&mut store, |caller: Caller<'_, HostState>, param: i32| {
        println!("Got {param} from WebAssembly");
        println!("My host state is: {}", caller.data());
    });

    // In order to create Wasm module instances and link their imports
    // and exports we require a `Linker`.
    let mut linker = <Linker<HostState>>::new(&engine);
    // Instantiation of a Wasm module requires defining its imports and then
    // afterwards we can fetch exports by name, as well as asserting the
    // type signature of the function with `get_typed_func`.
    //
    // Also before using an instance created this way we need to start it.
    linker.define("host", "hello", host_hello)?;
    let instance = linker
        .instantiate(&mut store, &module)?
        .start(&mut store)?;
    let hello = instance.get_typed_func::<(), ()>(&store, "hello")?;

    // And finally we can call the wasm!
    hello.call(&mut store, ())?;

    Ok(())
}

Modules§

core: Definitions from the wasmi_core crate.
errors: Defines some errors that may occur upon interaction with Wasmi.
state: Contains type states for the LinkerBuilder construction process.

Structs§

Caller: Represents the caller’s context when creating a host function via Func::wrap.
Config: Configuration for an Engine.
CustomSection: A Wasm custom section.
CustomSectionsIter: An iterator over the custom sections of a Wasm module.
EnforcedLimits: Stores customizable limits for the Engine when parsing or compiling Wasm modules.
Engine: The Wasmi interpreter.
EngineWeak: A weak reference to an Engine.
Error: The generic Wasmi root error type.
Export: An exported WebAssembly value.
ExportType: A descriptor for an exported WebAssembly value of a Module.
ExportsIter: An iterator over the Extern declarations of an Instance.
ExternRef: Represents a nullable opaque reference to any data within WebAssembly.
FuelCosts: Type storing all kinds of fuel costs of instructions.
Func: A Wasm or host function reference.
FuncRef: A nullable Func reference.
FuncType: A function type representing a function’s parameter and result types.
Global: A Wasm global variable reference.
GlobalType: The type of a global variable.
ImportType: A descriptor for an imported value into a Wasm Module.
Instance: An instantiated WebAssembly Module.
InstancePre: A partially instantiated Instance where the start function has not yet been executed.
Linker: A linker used to define module imports and instantiate module instances.
LinkerBuilder: A linker used to define module imports and instantiate module instances.
Memory: A Wasm linear memory reference.
MemoryType: The memory type of a linear memory.
Module: A parsed and validated WebAssembly module.
ModuleExportsIter: An iterator over the exports of a Module.
ModuleImportsIter: An iterator over the imports of a Module.
ResumableInvocation: State required to resume a Func invocation.
StackLimits: The configured limits of the Wasm stack.
Store: The store that owns all data associated to Wasm modules.
StoreContext: A temporary handle to a &Store<T>.
StoreContextMut: A temporary handle to a &mut Store<T>.
StoreLimits: Provides limits for a Store.
StoreLimitsBuilder: Used to build StoreLimits.
Table: A Wasm table reference.
TableType: A descriptor for a Table instance.
TypedFunc: A typed Func instance.
TypedResumableInvocation: State required to resume a TypedFunc invocation.

Enums§

CompilationMode: The chosen mode of Wasm to Wasmi bytecode compilation.
Extern: An external item to a WebAssembly module.
ExternType: The type of an Extern item.
Mutability: The mutability of a global variable.
ResumableCall: Returned by calling a Func in a resumable way.
TypedResumableCall: Returned by calling a TypedFunc in a resumable way.
Val: Runtime representation of a Wasm value.

Traits§