Crate tinywasm 

A small and portable WebAssembly interpreter.

tinywasm passes the full WebAssembly 3.0 core testsuite and supports the Lime1 interoperability target. It is designed for embedding in applications, tools, and no_std + alloc environments.

Getting started

Use parse_bytes to parse and validate a WebAssembly module, then instantiate it in a Store. A module can be reused, while each store owns its runtime state.

use tinywasm::{ModuleInstance, Store};

let wasm = include_bytes!("../../../examples/wasm/add.wasm");
let module = tinywasm::parse_bytes(wasm)?;

let mut store = Store::default();
let instance = ModuleInstance::instantiate(&mut store, &module, None)?;

let add = instance.func::<(i32, i32), i32>(&store, "add")?;
let result = add.call(&mut store, (1, 2))?;

assert_eq!(result, 3);

Typed functions convert Rust values directly. Use ModuleInstance::func_untyped and WasmValue when types are selected at runtime. References such as StructRef and ExternRef are owned handles tied to their store. Cloning a managed reference keeps its referent live.

Construct a store with a custom Engine and engine::Config to configure stack limits, fuel, and GC collection. A ResourceLimiter can bound guest memory, table, and GC heap growth.

References and GC

Runtime references belong to a Store. Passing a reference to another store returns Trap::InvalidStore. Managed references are cloneable owned handles, and their referents become collectible after the last handle is dropped. Nullable typed parameters and results use Option<T>. Use RefValue for dynamic reference values and Store::gc to request collection explicitly.

For more examples, see the examples directory.

Cargo features

• full: Enables archive, debug, parallel-parser, parser, state, and validate. Enabled by default.
• std: Enables std and parsing from files and streams. Enabled by default.
• parser: Enables tinywasm-parser and top-level parse helpers. Enabled by default.
• validate: Enables WebAssembly validation while parsing. Enabled by default and configurable through ParserOptions.
• parallel-parser: Parallelizes function parsing when std is enabled. Enabled by default.
• archive: Enables serialization and deserialization of the internal twasm format. Enabled by default.
• log: Enables integration with the log crate.
• send: Makes stores and store-local handles movable across threads.
• state: Adds store-owned host state for access from host callbacks. Enabled by default.
• portable-atomic: Supports targets without native atomic compare-and-swap.
• canonicalize-nans: Uses a canonical NaN for normalized NaN results.
• debug: Derives Debug for runtime types. Enabled by default.
• guest-debug: Exposes module-internal by-index inspection APIs (*_by_index).
• nightly-tail-calls: Uses Rust’s unstable explicit tail calls for interpreter dispatch. Requires nightly Rust (recommended for maximum performance).
• simd-x86: Enables x86-specific SIMD intrinsics and uses unsafe internally.

With default features disabled, tinywasm depends only on core, alloc, and libm, making it usable in no_std + alloc environments with a custom allocator.

Imports

To provide imports to a module, you can use the Imports struct. This struct allows you to register custom functions, globals, memories, tables, tags, and other modules to be linked into the module when it is instantiated.

See the Imports documentation for more information.

Re-exports

pub use engine::Engine;

pub use engine::StackConfig;

Modules

engine

Global configuration for the WebAssembly interpreter

parserparser

Re-export of tinywasm_parser. Requires parser feature.

types

Re-export of tinywasm_types.

Structs

AnyRef

An owned WebAssembly anyref.

ArrayRef

An owned WebAssembly arrayref.

EqRef

An owned WebAssembly eqref.

ExnRef

An owned WebAssembly exnref.

ExternRef

An owned WebAssembly externref.

FuncContext

The context of a host-function call

FuncExecution

Resumable execution for an untyped function call.

FuncExecutionTyped

Resumable execution for a typed function call.

FuncRef

A Store-aware WebAssembly function reference.

Function

A handle to a function instance in a store.

FunctionTyped

A typed function handle.

GcFieldType

Metadata for a struct field or array element.

GcRefType

Host-visible reference metadata with opaque concrete types.

GcType

An opaque canonical function, struct, or array type owned by a Store.

Global

A global instance in a store.

HostFunction

A reusable host function definition.

I31Ref

An owned WebAssembly i31ref.

Imports

Imports for a module instance

Memory

A memory instance in a store.

MemoryCursorstd

A cursor over a Memory instance.

Module

TinyWasm’s parsed and lowered representation of a WebAssembly module.

ModuleInstance

An instantiated WebAssembly module

Store

Runtime state used by WebAssembly instances and host functions.

StructRef

An owned WebAssembly structref.

Table

A table instance in a store.

Tag

A tag instance in a store.

Enums

Error

Errors that can occur for TinyWasm operations

ExecProgress

Progress for fuel-limited function execution.

Extern

An external import value.

ExternItem

A typed view over an exported extern value.

GcHeapType

Host-visible heap type metadata.

GcStorageType

Host-visible storage metadata for a GC field or array element.

GcTypeKind

The composite kind of a GcType.

GcValueType

Host-visible value metadata that does not expose concrete reference encodings.

LinkingError

Errors that can occur when linking a WebAssembly module

ParseErrorparser

Errors that can occur when parsing a WebAssembly module

RefValue

A host-facing WebAssembly reference value.

Trap

An execution or runtime trap.

WasmValue

A host-facing WebAssembly value.

Traits

FromWasmValues

Convert WebAssembly values into a Rust value or tuple.

IntoWasmValues

Convert a Rust value or tuple into WebAssembly values.

ResourceLimiter

Controls selected allocation requests from WebAssembly instances.

WasmTypes

Describes the WebAssembly value types produced by a Rust value or tuple shape.

WasmValueType

Describes the WebAssembly value types produced by a scalar Rust type.

Functions

parse_bytesparser

Parse a module from bytes

parse_fileparser and std

Parse a module from a file. Requires the std feature.

parse_streamparser and std

Parse a module from a stream. Requires the std feature.

Type Aliases

Result

A wrapper around core::result::Result for tinywasm operations