[][src]Crate susywasmi

susywasmi

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

Introduction

WebAssembly (susywasm) is a safe, portable and compact format that 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 module is well-formed and makes only allowed operations.

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

Instantiation

In order to execute code from a susywasm module, it must be instatiated. 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 susywasmi;
extern crate wabt;

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

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

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

    // 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 susywasm 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)),
    );
}

Re-exports

pub extern crate nan_preserving_float;

Modules

memory_units

WebAssembly-specific sizes and units.

Structs

FuncInstance

Runtime representation of a function.

FuncInvocation

A resumable invocation handle. This struct is returned by FuncInstance::invoke_resumable.

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 be thrown by susywasm 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.

ResumableError

A resumable invocation error.

RuntimeValue

Runtime representation of a value.

TrapKind

Error type which can be thrown by susywasm 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.