Skip to main content

Crate tinywasm

Crate tinywasm 

Source
Expand description

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

§Getting started

The easiest way to get started is to use the 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 [`types::WasmValue`]s
let func = instance.func::<(i32, i32), i32>(&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.

§Cargo features

  • std: Enables std and parsing from files and streams. Enabled by default.
  • log: Enables integration with the log crate. Enabled by default.
  • parser: Enables tinywasm-parser and top-level parse helpers. Enabled by default.
  • archive: Enables serialization and deserialization of the internal twasm format. Enabled by default.
  • canonicalize-nans: Canonicalizes NaN values. Enabled by default.
  • debug: Derives Debug for runtime types. Enabled by default.
  • parallel-parser: Parallelizes function parsing and validation 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 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, 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 allocates its backend on the first mutation.
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 the std feature.

Type Aliases§

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