[][src]Crate wasmer_runtime

Wasmer-runtime is a library that makes embedding WebAssembly in your application easy, efficient, and safe.

How to use Wasmer-Runtime

The easiest way is to use the instantiate function to create an Instance. Then you can use call or func and then call to call an exported function safely.

Here's an example:

Given this WebAssembly:

(module
  (type $t0 (func (param i32) (result i32)))
  (func $add_one (export "add_one") (type $t0) (param $p0 i32) (result i32)
    get_local $p0
    i32.const 1
    i32.add))

compiled into wasm bytecode, we can call the exported "add_one" function:

This example is not tested
static WASM: &'static [u8] = &[
    // The module above compiled to bytecode goes here.
    // ...
];

use wasmer_runtime::{
    instantiate,
    Value,
    imports,
    error,
    Func,
};

fn main() -> error::Result<()> {
    // We're not importing anything, so make an empty import object.
    let import_object = imports! {};

    let mut instance = instantiate(WASM, &import_object)?;

    let add_one: Func<i32, i32> = instance.exports.get("add_one")?;

    let value = add_one.call(42)?;

    assert_eq!(value, 43);

    Ok(())
}

Additional Notes:

wasmer-runtime is built to support multiple compiler backends. Currently, we support the Singlepass, Cranelift, and LLVM compilers with the wasmer-singlepass-backend, wasmer-clif-backend, and wasmer-llvm-backend crates, respectively.

You can specify the compiler you wish to use with the compile_with function or use the default with the compile function.

Modules

cache

The cache module provides the common data structures used by compiler backends to allow serializing compiled wasm code to a binary format. The binary format can be persisted, and loaded to allow skipping compilation and fast startup.

error

The error module contains the data structures and helper functions used to implement errors that are produced and returned from the wasmer runtime.

memory

The memory module contains the implementation data structures and helper functions used to manipulate and access wasm memory.

types

Types used in the Wasm runtime and conversion functions.

units

Various unit types.

wasm

Various types exposed by the Wasmer Runtime.

Macros

func

Helper macro to create a new Func object using the provided function pointer.

imports

Generate an ImportObject safely.

Structs

Array

The Array marker type. This type can be used like WasmPtr<T, Array> to get access to methods

CodeVersion

A CodeVersion is a container for a unit of generated code for a module.

CompilerConfig

Configuration data for the compiler

Ctx

The context of the currently running WebAssembly instance.

DynFunc

A representation of an exported WebAssembly function.

Features

Controls which experimental features will be enabled. Features usually have a corresponding WebAssembly proposal.

Func

Represents a function that can be used by WebAssembly.

Global

A handle to a Wasm Global

ImportObject

All of the import data used when instantiating.

Instance

An instantiated WebAssembly module.

Item

The Item marker type. This is the default and does not usually need to be specified.

Memory

A shared or unshared wasm linear memory.

MiddlewareChain

A container for a chain of middlewares.

Module

A compiled WebAssembly module.

StreamingCompiler

A streaming compiler which is designed to generated code for a module based on a stream of wasm parser events.

Table

Container with a descriptor and a reference to a table storage.

WasmPtr

A zero-cost type that represents a pointer to something in Wasm linear memory.

Enums

Backend

Enum used to select which compiler should be used to generate code.

ExceptionCode

The code of an exception.

Export

Kind of WebAssembly export.

Value

Represents a WebAssembly value.

Constants

VERSION

The current version of this crate.

Traits

Compiler
LikeNamespace

This trait represents objects that act as a namespace for imports. For example, an Instance or ImportObject could be considered namespaces that could provide imports to an instance.

Functions

compile

Compile WebAssembly binary code into a Module. This function is useful if it is necessary to compile a module before it can be instantiated (otherwise, the instantiate function should be used).

compile_with

Compile a Module using the provided compiler from WebAssembly binary code. This function is useful if it is necessary to a compile a module before it can be instantiated and must be used if you wish to use a different backend from the default.

compile_with_config

The same as compile but takes a CompilerConfig for the purpose of changing the compiler's behavior

compile_with_config_with

The same as compile_with_config but takes a Compiler for the purpose of changing the backend.

compiler_for_backend

Get the Compiler as a trait object for the given Backend. Returns Option because support for the requested Compiler may not be enabled by feature flags.

default_compiler

Get a single instance of the default compiler to use.

instantiate

Compile and instantiate WebAssembly code without creating a Module.

pop_code_version

Pops a CodeVersion from the current code versions.

push_code_version

Pushes a new CodeVersion to the current code versions.

validate

Perform validation as defined by the WebAssembly specification. Returns true if validation succeeded, false if validation failed.