Crate tinywasm 

tinywasm provides a small, portable WebAssembly interpreter with support for the WebAssembly MVP, WebAssembly 2.0, and a growing set of newer proposals. It is designed to stay lightweight while still being practical to embed in applications, tools, and no_std + alloc environments.

Features

• std
  Enables parsing from files and streams. Enabled by default.
• log
  Enables integration with the log crate. Enabled by default.
• parser
  Enables the bundled tinywasm-parser crate and top-level parse helpers. Enabled by default.
• archive
  Enables serialization and deserialization of compiled modules in the internal twasm format. Enabled by default.
• canonicalize-nans
  Canonicalizes NaN values to a single representation. Enabled by default.
• debug
  Derives Debug for runtime types. Enabled by default.
• parallel-parser
  Parallelizes function parsing and validation across threads when std is enabled. Enabled by default.
• guest-debug
  Exposes module-internal by-index inspection APIs (*_by_index).
• simd-x86
  Enables x86-specific SIMD intrinsics for selected operations and uses unsafe internally.

With default features disabled, tinywasm only depends on core, alloc, and libm. By disabling std, you can use tinywasm in no_std environments. This requires a custom allocator and removes support for parsing from files and streams, but otherwise the API is the same.

Getting Started

The easiest way to get started is to use the crate::parse_bytes function to load a WebAssembly module from bytes. This will parse the module and validate it, returning a Module that can be used to instantiate the module.

use tinywasm::{ModuleInstance, Store};

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

// # Create a new store
// Stores are used to allocate objects like functions and globals
let mut store = Store::default();

// # Instantiate the module
// This will allocate the module and its globals into the store
// and execute the module's start function.
let instance = ModuleInstance::instantiate(&mut store, &module, None)?;

// # Get a typed handle to the exported "add" function
// Alternatively, you can use `instance.func_untyped` to get an untyped handle
// that takes and returns [`WasmValue`]s
let func = instance.func::<(i32, i32), i32>(&mut store, "add")?;
let res = func.call(&mut store, (1, 2))?;

assert_eq!(res, 3);

For non-default runtime behavior, construct a Store with a custom Engine and engine::Config to control stack sizing, fuel accounting, memory backends, and trap-on-OOM behavior.

For more examples, see the examples directory.

Imports

To provide imports to a module, you can use the Imports struct. This struct allows you to register custom functions, globals, memories, tables, 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::LazyLinearMemory;

pub use engine::LinearMemory;

pub use engine::MemoryBackend;

pub use engine::PagedMemory;

pub use engine::StackConfig;

pub use engine::VecMemory;

Modules

engine

Global configuration for the WebAssembly interpreter

parserparser

Re-export of tinywasm_parser. Requires parser feature.

types

Re-export of tinywasm_types.

Structs

ExternName

Name of an import

FuncContext

The context of a host-function call

FuncExecution

Resumable execution for an untyped function call.

FuncExecutionTyped

Resumable execution for a typed function call.

Function

A function handle

FunctionTyped

A typed function handle

Global

A global instance in a store.

HostFunction

A host function

Imports

Imports for a module instance

LazyLinearMemory

A linear memory wrapper that materializes its inner backend on first access.

Memory

A memory instance in a store.

MemoryBackend

Configures how runtime memory instances are created.

MemoryCursorstd

A cursor over a Memory instance.

Module

A TinyWasm WebAssembly Module

ModuleInstance

An instantiated WebAssembly module

PagedMemory

A sparse chunked linear memory.

Store

Global state that can be manipulated by WebAssembly programs

Table

A table instance in a store.

VecMemory

A contiguous Vec<u8>-backed linear memory.

WasmTupleChain

A helper type for using tuples of arbitrary number of elements as function parameters or results, by concatenating the Wasm types of each element.

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.

LinkingError

Errors that can occur when linking a WebAssembly module

ParseErrorparser

Errors that can occur when parsing a WebAssembly module

Trap

A WebAssembly trap

Traits

LinearMemory

Backend storage for a linear memory

ToWasmTypes

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

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 parser and std features.

Type Aliases

Result

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