Crate wasmi[−][src]

wasmi

This library allows to load WebAssembly modules in binary format and invoke functions on them.

Introduction

WebAssembly (wasm) is a safe, portable, compact format that designed for efficient execution.

Wasm code is distributed in a form of modules, that contains definitions of:

functions,
global variables,
linear memories,
tables.

and this definitions can be imported. Also, each definition can be exported.

In addition to definitions, modules can define initialization data for their memories or tables that takes the form of segments copied to given offsets. They can also define a start function that is automatically executed.

Loading and Validation

Before execution a module should be validated. This process checks that module is well-formed and makes only allowed operations.

Valid modules can't access memory out of it's sandbox, can't cause stack underflow and can call functions only with correct signatures.

Instantiatiation

In order to execute code in wasm module it should be instatiated. Instantiation includes the following steps:

Create an empty module instance,
Resolve definition instances for each declared import in the module,
Instantiate definitions declared in the module (e.g. allocate global variables, allocate linear memory, etc),
Initialize memory and table contents by copiying segments into them,
Execute start function, if any.

After these steps, module instance are ready to execute functions.

Execution

It is allowed to only execute functions which are exported by a module. Functions can either return a result or trap (e.g. there can't be linking-error at the middle of execution). This property is ensured by the validation process.

Examples

extern crate wasmi;
extern crate wabt;

use wasmi::{ModuleInstance, ImportsBuilder, NopExternals, RuntimeValue};

fn main() {
    // Parse WAT (WebAssembly Text format) into wasm bytecode.
    let wasm_binary: Vec<u8> =
        wabt::wat2wasm(
            r#"
            (module
                (func (export "test") (result i32)
                    i32.const 1337
                )
            )
            "#,
        )
        .expect("failed to parse wat");

    // Load wasm binary and prepare it for instantiation.
    let module = wasmi::Module::from_buffer(&wasm_binary)
        .expect("failed to load wasm");

    // Instantiate a module with empty imports and
    // asserting that there is no `start` function.
    let instance =
        ModuleInstance::new(
            &module,
            &ImportsBuilder::default()
        )
        .expect("failed to instantiate wasm module")
        .assert_no_start();

    // Finally, invoke exported function "test" with no parameters
    // and empty external function executor.
    assert_eq!(
        instance.invoke_export(
            "test",
            &[],
            &mut NopExternals,
        ).expect("failed to execute export"),
        Some(RuntimeValue::I32(1337)),
    );
}

Modules

memory_units

WebAssembly-specific sizes and units.

Structs

FuncInstance	Runtime representation of a function.
FuncRef	Reference to a function (See `FuncInstance` for details).
GlobalDescriptor	Description of a global variable.
GlobalInstance	Runtime representation of a global variable (or `global` for short).
GlobalRef	Reference to a global variable (See `GlobalInstance` for details).
ImportsBuilder	Convenience builder of `ImportResolver`.
MemoryDescriptor	Description of a linear memory.
MemoryInstance	Runtime representation of a linear memory (or `memory` for short).
MemoryRef	Reference to a memory (See `MemoryInstance` for details).
Module	Deserialized module prepared for instantiation.
ModuleInstance	A module instance is the runtime representation of a module.
ModuleRef	Reference to a `ModuleInstance`.
NopExternals	Implementation of `Externals` that just traps on `invoke_index`.
NotStartedModuleRef	Mostly instantiated `ModuleRef`.
RuntimeArgs	Wrapper around slice of `RuntimeValue` for using it as an argument list conveniently.
Signature	Signature of a function.
TableDescriptor	Description of a table.
TableInstance	Runtime representation of a table.
TableRef	Reference to a table (See `TableInstance` for details).
Trap	Error type which can thrown by wasm code or by host environment.

Enums

Error	Internal interpreter error.
ExternVal	An external value is the runtime representation of an entity that can be imported or exported.
RuntimeValue	Runtime representation of a value.
TrapKind	Error type which can thrown by wasm code or by host environment.
ValueType	Type of a value.

Constants

LINEAR_MEMORY_PAGE_SIZE

Size of a page of linear memory - 64KiB.

Traits

Externals	Trait that allows to implement host functions.
FromRuntimeValue	Trait for creating value from a `RuntimeValue`.
HostError	Trait that allows the host to return custom error.
ImportResolver	Resolver of a module's dependencies.
ModuleImportResolver	Version of `ImportResolver` specialized for a single module.