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 ofstd
andstd::io
for parsing from files and streams. This is enabled by default.logging
Enables logging using thelog
crate. This is enabled by default.parser
Enables thetinywasm-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
. Requiresparser
feature. - types
- Re-export of
tinywasm_types
.
Structs§
- Extern
Name - Name of an import
- Func
Context - The context of a host-function call
- Func
Handle - A function handle
- Func
Handle Typed - A typed function handle
- Host
Function - A host function
- Imports
- Imports for a module instance
- Memory
Ref - A reference to a memory instance
- Memory
RefMut - A borrowed reference to a memory instance
- Module
- A WebAssembly Module
- Module
Instance - 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
- Linking
Error - Errors that can occur when linking a WebAssembly module
- Parse
Error - Errors that can occur when parsing a WebAssembly module
- Trap
- A WebAssembly trap
Traits§
- Memory
String Ext - Convenience methods for loading strings from memory
Type Aliases§
- Result
- A wrapper around
core::result::Result
for tinywasm operations