Crate wasmi

source ·
Expand description

wasmi

This library allows WebAssembly modules to be loaded in binary format and their functions invoked.

Introduction

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

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

  • functions,
  • global variables,
  • linear memory instances and
  • tables.

Each of these definitions can be imported and exported.

In addition to these definitions, modules can define initialization data for their memory or tables. This initialization data can take the form of segments, copied to given offsets. They can also define a start function that is automatically executed when the module is loaded.

Loading and Validation

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

A valid module can’t access memory outside its sandbox, can’t cause stack underflows and can only call functions with correct signatures.

Instantiation

In order to execute code from a wasm module, it must be instantiated. Instantiation includes the following steps:

  1. Creating an empty module instance.
  2. Resolving the definition instances for each declared import in the module.
  3. Instantiating definitions declared in the module (e.g. allocate global variables, allocate linear memory, etc.).
  4. Initializing memory and table contents by copying segments into them.
  5. Executing the start function, if any.

After these steps, the module instance is ready to execute functions.

Execution

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

Examples

extern crate wasmi;
extern crate wat;

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

fn main() {
    // Parse WAT (WebAssembly Text format) into wasm bytecode.
    let wasm_binary: Vec<u8> =
        wat::parse_str(
            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
    // assert that there is no `start` function.
    let instance =
        ModuleInstance::new(
            &module,
            &ImportsBuilder::default()
        )
        .expect("failed to instantiate wasm module")
        .assert_no_start();

    // Finally, invoke the 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

Structs

Enums

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

Constants

Traits