Crate wasm3x 

Safe, wasmi/wasmtime-shaped Rust bindings for the Wasm3 interpreter.

This crate wraps the raw wasm3x-sys C-API in a small, safe, and efficient API modeled after wasmi and wasmtime:

• Engine wraps a shared Wasm3 environment and holds the Config.
• Store owns all runtime state of the modules instantiated into it.
• Module is a parsed module that can be instantiated many times.
• Linker provides host functions and instantiates modules.
• Instance, Func/TypedFunc, Memory, and Global give access to the instantiated module.

Example

use wasm3x::{Engine, Store, Module, Linker};

let engine = Engine::default();
let mut store = Store::new(&engine, ());
let module = Module::new(&engine, &wasm_bytes()).unwrap();
let linker = Linker::<()>::new(&engine);
let instance = linker.instantiate_and_start(&mut store, &module).unwrap();
let add = instance.get_typed_func::<(i32, i32), i32>(&store, "add").unwrap();
assert_eq!(add.call(&mut store, (2, 3)).unwrap(), 5);

Differences from wasmi/wasmtime (Wasm3 limitations)

• Function lookup is runtime-global by name. Wasm3 finds exported functions across all modules loaded into the runtime; there is no per-instance namespace and no lookup by index. This matches the common one-module-per-store usage.
• No import/export enumeration. Wasm3 does not expose a module’s imports or exports, so there is no Module::imports()/exports(). Host functions are provided through a Linker and linked by name.
• Host functions receive a Caller but cannot re-enter Wasm. A host function gets a Caller<'_, T> for &mut T host-data and linear Memory access, but — unlike Wasmtime — it may not call back into Wasm: Wasm3’s public call entry points run from the base of the runtime stack and would corrupt the suspended frame. Host functions also return at most one value (Wasm3’s signature format encodes a single result); Wasm functions you call may be multi-value.
• Light validation. Wasm3 is not a fully validating runtime; treat Module::new validation as best-effort.
• Single-threaded. Engine and Store are neither Send nor Sync.

Structs

Caller

The context passed as the first argument to every host function.

Config

Configuration for an Engine.

Engine

A Wasm3 execution environment, shared by all stores created from it.

Error

An error that can occur when working with the Wasm3 interpreter.

Func

A callable Wasm function belonging to a Store.

FuncType

The signature (parameter and result types) of a Wasm function.

Global

A handle to an exported global variable of an Instance.

GlobalType

The type of a global variable: its value type and mutability.

Instance

A handle to an instantiated module within a Store.

Linker

A registry of host functions used to satisfy module imports and instantiate Modules into a Store.

Memory

A handle to the linear memory of a Store.

Module

A parsed Wasm module that can be instantiated into a Store.

Store

Owns the runtime state (memory, globals, tables, compiled code) of the modules instantiated into it, together with arbitrary host data.

StoreContext

A shared view of a Store’s runtime, produced by AsContext::as_context.

StoreContextMut

An exclusive view of a Store’s runtime, produced by AsContextMut::as_context_mut. Used by handle methods that mutate. See AsContext for why this uniform view exists.

TypedFunc

A statically typed view of a Func with compile-time known parameter and result types. Type checks happen once, at construction.

Enums

CompilationMode

The strategy used to compile Wasm functions to Wasm3’s internal bytecode.

Mutability

Whether a global variable can be mutated after instantiation.

Val

A runtime Wasm value.

ValType

The type of a Wasm value.

Traits

AsContext

A type that can yield a shared StoreContext: Store<T>, a context, or a Caller, plus &/&mut references to any of them.

AsContextMut

A type that can yield an exclusive StoreContextMut.

IntoFunc

Rust closures and functions usable as Wasm3 host functions.

WasmParams

Types usable as the parameter list of a TypedFunc or host function.

WasmResults

Types usable as the result list of a TypedFunc or host function.

WasmRet

Types usable as the return value of a host function: a value, a tuple of values, or a Result thereof.

WasmTy

A primitive Wasm type usable as a typed function parameter or result.

Type Aliases

Result

A specialized Result type for this crate.