Crate 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 wasmi::*;

// In this simple example we are going to compile the below Wasm source,
// instantiate a Wasm module from it and call its exported "hello" function.
fn main() -> Result<(), wasmi::Error> {
    let wasm = r#"
        (module
            (import "host" "hello" (func $host_hello (param i32)))
            (func (export "hello")
                (call $host_hello (i32.const 3))
            )
        )
    "#;
    // 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();
    // Now we can compile the above Wasm module with the given Wasm source.
    let module = Module::new(&engine, wasm)?;

    // Wasm objects operate within the context of a Wasm `Store`.
    //
    // Each `Store` has a type parameter to store host specific data.
    // In this example the host state is a simple `u32` type with value `42`.
    type HostState = u32;
    let mut store = Store::new(&engine, 42);

    // A linker can be used to instantiate Wasm modules.
    // The job of a linker is to satisfy the Wasm module's imports.
    let mut linker = <Linker<HostState>>::new(&engine);
    // We are required to define all imports before instantiating a Wasm module.
    linker.func_wrap("host", "hello", |caller: Caller<'_, HostState>, param: i32| {
        println!("Got {param} from WebAssembly and my host state is: {}", caller.data());
    });
    let instance = linker
        .instantiate(&mut store, &module)?
        .start(&mut store)?;
    // Now we can finally query the exported "hello" function and call it.
    instance
        .get_typed_func::<(), ()>(&store, "hello")?
        .call(&mut store, ())?;
    Ok(())
}

§Crate Features

Feature	Crates	Description
`std`	`wasmi` `wasmi_core` `wasmi_ir` `wasmi_collections`	Enables usage of Rust’s standard library. This may have some performance advantages when enabled. Disabling this feature makes Wasmi compile on platforms that do not provide Rust’s standard library such as many embedded platforms. Enabled by default.
`wat`	`wasmi`	Enables support to parse Wat encoded Wasm modules. Enabled by default.
`simd`	`wasmi` `wasmi_core` `wasmi_ir` `wasmi_cli`	Enables support for the Wasm `simd` proposal. Note that this may introduce execution overhead and increased memory consumption for Wasm executions that do not need Wasm `simd` functionality. Disabled by default.
`hash-collections`	`wasmi` `wasmi_collections`	Enables use of hash-map based collections in Wasmi internals. This might yield performance improvements in some use cases. Disabled by default.
`prefer-btree-collections`	`wasmi` `wasmi_collections`	Enforces use of btree-map based collections in Wasmi internals. This may yield performance improvements and memory consumption decreases in some use cases. Also it enables Wasmi to run on platforms that have no random source. Disabled by default.
`extra-checks`	`wasmi`	Enables extra runtime checks in the Wasmi executor. Expected execution overhead is ~20%. Enable this if your focus is on safety. Disable this for maximum execution performance. Disabled by default.

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.
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.
MemoryTypeBuilder: A builder for MemoryTypes.
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§

CallHook: Argument to the callback set by Store::call_hook to indicate why the callback was invoked.
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§

AsContext: A trait used to get shared access to a Store in Wasmi.
AsContextMut: A trait used to get exclusive access to a Store in Wasmi.
IntoFunc: Closures and functions that can be used as host functions.
Read: Types implementing this trait act as byte streams.
ResourceLimiter: Used by hosts to limit resource consumption of instances.
WasmParams: The typed parameters of a TypedFunc.
WasmResults: The typed results of a TypedFunc.
WasmRet: Types and type sequences that can be used as return values of host functions.
WasmTy: Types that can be used as parameters or results of host functions.
WasmTyList: A list of WasmTy types.