Crate tinywasm

Source
Expand description

A tiny WebAssembly Runtime written in Rust

TinyWasm provides a minimal WebAssembly runtime for executing WebAssembly modules. It currently supports all features of the WebAssembly MVP specification and is designed to be easy to use and integrate in other projects.

§Features

  • std
    Enables the use of std and std::io for parsing from files and streams. This is enabled by default.
  • logging
    Enables logging using the log crate. This is enabled by default.
  • parser
    Enables the tinywasm-parser crate. This is enabled by default.
  • archive
    Enables pre-parsing of archives. This is enabled by default.

With all these 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. Additionally, to have proper error types in no_std, you currently need a nightly compiler to use the unstable 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.exported_func::<(i32, i32), i32>(&mut store, "add")?;
let res = func.call(&mut store, (1, 2))?;

assert_eq!(res, 3);

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

Modules§

interpreter
Runtime for executing WebAssembly modules.
parser
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
FuncHandle
A function handle
FuncHandleTyped
A typed function handle
HostFunction
A host function
Imports
Imports for a module instance
MemoryRef
A reference to a memory instance
MemoryRefMut
A borrowed reference to a memory 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

Traits§

MemoryStringExt
Convenience methods for loading strings from memory

Type Aliases§

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