Crate tinywasm

A tiny WebAssembly Runtime written in Rust

TinyWasm provides a minimal WebAssembly runtime for executing WebAssembly modules. It currently supports a subset of the WebAssembly MVP specification and is intended to be useful for embedded systems and other environments where a full-featured runtime is not required.

Features

• std (default): Enables the use of std and std::io for parsing from files and streams.
• logging (default): Enables logging via the log crate.
• parser (default): Enables the tinywasm_parser crate for parsing WebAssembly modules.

No-std support

TinyWasm supports no_std environments by disabling the std feature and registering a custom allocator. This removes support for parsing from files and streams, but otherwise the API is the same. Additionally, to have proper error types, you currently need a nightly compiler to have the error trait in core.

Getting Started

The easiest way to get started is to use the Module::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::{Store, Module};

// Load a module from bytes
let wasm = include_bytes!("../../../examples/wasm/add.wasm");
let module = Module::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.
// Every ModuleInstance has its own ID space for functions, globals, etc.
let instance = module.instantiate(&mut store, None)?;

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

assert_eq!(res, 3);

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 runtime::InterpreterRuntime;

Modules

• parser
  Re-export of tinywasm_parser. Requires parser feature.
• runtime
  Runtime for executing WebAssembly modules.
• types
  Re-export of tinywasm_types.

Structs

• ExternName
  Name of an import
• FuncContext
  The context of a host-function call
• FuncHandle
  A function handle
• FuncHandleTyped
  A typed function handle
• HostFunction
  A host function
• Imports
  Imports for a module instance
• Module
  A WebAssembly Module
• ModuleInstance
  An instanciated WebAssembly module
• Store
  Global state that can be manipulated by WebAssembly programs

Enums

• Error
  Errors that can occur for TinyWasm operations
• Extern
  An external value
• Function
  The internal representation of a function
• LinkingError
  Errors that can occur when linking a WebAssembly module
• ParseError
  Errors that can occur when parsing a WebAssembly module
• Trap
  A WebAssembly trap

Type Aliases

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