Crate wasmer

Expand description

Wasmer is the most popular WebAssembly runtime for Rust. It supports JIT (Just In Time) and AOT (Ahead Of Time) compilation as well as pluggable compilers suited to your needs.

It’s designed to be safe and secure, and runnable in any kind of environment.

§Usage

Here is a small example of using Wasmer to run a WebAssembly module written with its WAT format (textual format):

use wasmer::{Store, Module, Instance, Value, imports};

fn main() -> anyhow::Result<()> {
    let module_wat = r#"
    (module
      (type $t0 (func (param i32) (result i32)))
      (func $add_one (export "add_one") (type $t0) (param $p0 i32) (result i32)
        local.get $p0
        i32.const 1
        i32.add))
    "#;

    let mut store = Store::default();
    let module = Module::new(&store, &module_wat)?;
    // The module doesn't import anything, so we create an empty import object.
    let import_object = imports! {};
    let instance = Instance::new(&mut store, &module, &import_object)?;

    let add_one = instance.exports.get_function("add_one")?;
    let result = add_one.call(&mut store, &[Value::I32(42)])?;
    assert_eq!(result[0], Value::I32(43));

    Ok(())
}

Discover the full collection of examples.

§Overview of the Features

Wasmer is not only fast, but also designed to be highly customizable:

Pluggable compilers — A compiler is used by the engine to transform WebAssembly into executable code:
- wasmer-compiler-singlepass provides a fast compilation-time but an unoptimized runtime speed,
- wasmer-compiler-cranelift provides the right balance between compilation-time and runtime performance, useful for development,
- wasmer-compiler-llvm provides a deeply optimized executable code with the fastest runtime speed, ideal for production.
Headless mode — Once a WebAssembly module has been compiled, it is possible to serialize it in a file for example, and later execute it with Wasmer with headless mode turned on. Headless Wasmer has no compiler, which makes it more portable and faster to load. It’s ideal for constrainted environments.
Cross-compilation — Most compilers support cross-compilation. It means it possible to pre-compile a WebAssembly module targetting a different architecture or platform and serialize it, to then run it on the targetted architecture and platform later.
Run Wasmer in a JavaScript environment — With the js Cargo feature, it is possible to compile a Rust program using Wasmer to WebAssembly. In this context, the resulting WebAssembly module will expect to run in a JavaScript environment, like a browser, Node.js, Deno and so on. In this specific scenario, there is no engines or compilers available, it’s the one available in the JavaScript environment that will be used.

Wasmer ships by default with the Cranelift compiler as its great for development purposes. However, we strongly encourage to use the LLVM compiler in production as it performs about 50% faster, achieving near-native speeds.

Note: if one wants to use multiple compilers at the same time, it’s also possible! One will need to import them directly via each of the compiler crates.

§Table of Contents

WebAssembly Primitives
- Externs
  - Functions
  - Memories
  - Globals
  - Tables
Project Layout
- Engines
- Compilers
Cargo Features
Using Wasmer in a JavaScript environment

§WebAssembly Primitives

In order to make use of the power of the wasmer API, it’s important to understand the primitives around which the API is built.

Wasm only deals with a small number of core data types, these data types can be found in the Value type.

In addition to the core Wasm types, the core types of the API are referred to as “externs”.

§Externs

An Extern is a type that can be imported or exported from a Wasm module.

To import an extern, simply give it a namespace and a name with the imports! macro:

let memory = Memory::new(&mut store, MemoryType::new(1, None, false)).unwrap();
imports! {
    "env" => {
         "my_function" => Function::new_typed(&mut store, || println!("Hello")),
         "memory" => memory,
    }
}

And to access an exported extern, see the Exports API, accessible from any instance via instance.exports:

let memory = instance.exports.get_memory("memory")?;
let memory: &Memory = instance.exports.get("some_other_memory")?;
let add: TypedFunction<(i32, i32), i32> = instance.exports.get_typed_function(&mut store, "add")?;
let result = add.call(&mut store, 5, 37)?;
assert_eq!(result, 42);

These are the primary types that the wasmer API uses.

§Functions

There are 2 types of functions in wasmer:

Wasm functions,
Host functions.

A Wasm function is a function defined in a WebAssembly module that can only perform computation without side effects and call other functions.

Wasm functions take 0 or more arguments and return 0 or more results. Wasm functions can only deal with the primitive types defined in Value.

A Host function is any function implemented on the host, in this case in Rust.

Thus WebAssembly modules by themselves cannot do anything but computation on the core types in Value. In order to make them more useful we give them access to the outside world with imports!.

If you’re looking for a sandboxed, POSIX-like environment to execute Wasm in, check out the wasmer-wasix crate for our implementation of WASI, the WebAssembly System Interface, and WASIX, the Extended version of WASI.

In the wasmer API we support functions which take their arguments and return their results dynamically, Function, and functions which take their arguments and return their results statically, TypedFunction.

§Memories

Memories store data.

In most Wasm programs, nearly all data will live in a Memory.

This data can be shared between the host and guest to allow for more interesting programs.

§Globals

A Global is a type that may be either mutable or immutable, and contains one of the core Wasm types defined in Value.

§Tables

A Table is an indexed list of items.

§Project Layout

The Wasmer project is divided into a number of crates, below is a dependency graph with transitive dependencies removed.

While this crate is the top level API, we also publish crates built on top of this API that you may be interested in using, including:

wasmer-cache for caching compiled Wasm modules,
wasmer-wasix for running Wasm modules compiled to the WASI ABI.

The Wasmer project has two major abstractions:

Engine,
Compilers.

These two abstractions have multiple options that can be enabled with features.

§Engine

The engine is a system that uses a compiler to make a WebAssembly module executable.

§Compilers

A compiler is a system that handles the details of making a Wasm module executable. For example, by generating native machine code for each Wasm function.

§Cargo Features

This crate comes in 2 flavors:

sys (enabled), where wasmer will be compiled to a native executable which provides compilers, engines, a full VM etc.
js (disabled), where wasmer will be compiled to WebAssembly to run in a JavaScript host (see Using Wasmer in a JavaScript environment).

Consequently, we can group the features by the sys or js features.

§Features for the `sys` feature group (enabled)

The default features can be enabled with the sys-default feature.

The features for the sys feature group can be broken down into 2 kinds: features that enable new functionality and features that set defaults.

The features that enable new functionality are:

cranelift (enabled), enables Wasmer’s [Cranelift compiler][wasmer-compiler-cranelift],
llvm (disabled), enables Wasmer’s [LLVM compiler][wasmer-compiler-lvm],
singlepass (enabled), enables Wasmer’s [Singlepass compiler][wasmer-compiler-singlepass],
wat (enabled), enables wasmer to parse the WebAssembly text format,
compilation (enabled), enables compilation with the wasmer engine.

§Features for the `js` feature group (disabled)

The default features can be enabled with the js-default feature.

Here are the detailed list of features:

wasm-types-polyfill (disabled), parses the Wasm file, allowing to do type reflection of the inner Wasm types. It adds 100kb to the Wasm bundle (28kb gzipped). It is possible to disable it and to use Module::set_type_hints manually instead for a lightweight alternative. This is needed until the Wasm JS introspection API proposal is adopted by browsers,
wat (enabled), allows to read a Wasm file in its text format. This feature is normally used only in development environments. It will add around 650kb to the Wasm bundle (120Kb gzipped).

§Using Wasmer in a JavaScript environment

Imagine a Rust program that uses this wasmer crate to execute a WebAssembly module. It is possible to compile this Rust progam to WebAssembly by turning on the js Cargo feature of this wasmer crate.

Here is a small example illustrating such a Rust program, and how to compile it with wasm-pack and wasm-bindgen:

use wasm_bindgen::prelude::*;
use wasmer::{imports, Instance, Module, Store, Value};

#[wasm_bindgen]
pub extern fn do_add_one_in_wasmer() -> i32 {
    let module_wat = r#"
    (module
      (type $t0 (func (param i32) (result i32)))
      (func $add_one (export "add_one") (type $t0) (param $p0 i32) (result i32)
        local.get $p0
        i32.const 1
        i32.add))
    "#;
    let mut store = Store::default();
    let module = Module::new(&store, &module_wat).unwrap();
    // The module doesn't import anything, so we create an empty import object.
    let import_object = imports! {};
    let instance = Instance::new(&mut store, &module, &import_object).unwrap();

    let add_one = instance.exports.get_function("add_one").unwrap();
    let result = add_one.call(&mut store, &[Value::I32(42)]).unwrap();
    assert_eq!(result[0], Value::I32(43));

    result[0].unwrap_i32()
}

Note that it’s the same code as above with the former example. The API is the same!

Then, compile with wasm-pack build. Take care of using the js or js-default Cargo features.

Re-exports§

pub use sys::*;

Modules§

sys: The sys engine.
vm: The vm module re-exports wasmer-vm types.

Macros§

imports: Generate an Imports easily with the imports! macro.

Structs§

Bytes: Units of WebAssembly memory in terms of 8-bit bytes.
Engine: The engine type
EngineRef: A temporary handle to an Engine EngineRef can be used to build a Module It can be created directly with an Engine Or from anything implementing AsEngineRef like from Store typicaly.
ExportType: A descriptor for an exported WebAssembly value.
Exports: Exports is a special kind of map that allows easily unwrapping the types of instances.
ExportsIterator: An iterator over exports.
ExternRef: An opaque reference to some data. This reference can be passed through Wasm.
FrameInfo: Description of a frame in a backtrace.
Function: A WebAssembly function instance.
FunctionEnv: An opaque reference to a function environment. The function environment data is owned by the Store.
FunctionEnvMut: A temporary handle to a FunctionEnv.
FunctionType: The signature of a function that is either implemented in a Wasm module or exposed to Wasm by the host.
Global: A WebAssembly global instance.
GlobalType: WebAssembly global.
ImportType: A descriptor for an imported value into a wasm module.
Imports: All of the import data used when instantiating.
Instance: A WebAssembly Instance is a stateful, executable instance of a WebAssembly Module.
LocalFunctionIndex: Index type of a function defined locally inside the WebAssembly module.
Memory: A WebAssembly memory instance.
Memory32: Marker trait for 32-bit memories.
Memory64: Marker trait for 64-bit memories.
MemoryLocation: Location in a WebAssembly memory.
MemoryType: A descriptor for a WebAssembly memory type.
MemoryView: A WebAssembly memory view.
MiddlewareError: A error in the middleware.
Module: A WebAssembly Module contains stateless WebAssembly code that has already been compiled and can be instantiated multiple times.
Pages: Units of WebAssembly pages (as specified to be 65,536 bytes).
RuntimeError: A struct representing an aborted instruction execution, with a message indicating the cause.
SharedMemory: A handle that exposes operations only relevant for shared memories.
Store: The store represents all global state that can be manipulated by WebAssembly programs. It consists of the runtime representation of all instances of functions, tables, memories, and globals that have been allocated during the lifetime of the abstract machine.
StoreId: Unique ID to identify a context.
StoreMut: A temporary handle to a Store.
StoreObjects: Set of objects managed by a context.
StoreRef: A temporary handle to a Store.
Table: A WebAssembly table instance.
TableType: A descriptor for a table in a WebAssembly module.
Target: This is the target that we will use for compiling the WebAssembly ModuleInfo, and then run it.
Triple: A target “triple”. Historically such things had three fields, though they’ve added additional fields over time.
TypedFunction: A WebAssembly function that can be called natively (using the Native ABI).
WasmPtr: A zero-cost type that represents a pointer to something in Wasm linear memory.
WasmRef: Reference to a value in Wasm memory.
WasmSlice: Reference to an array of values in Wasm memory.
WasmSliceAccess: Provides direct memory access to a piece of memory that is owned by WASM
WasmSliceIter: Iterator over the elements of a WasmSlice.

Enums§

Architecture: The “architecture” field, which in some cases also specifies a specific subarchitecture.
AtomicsError: Error that can occur during atomic operations. (notify/wait)
CallingConvention: The calling convention, which specifies things like which registers are used for passing arguments, which registers are callee-saved, and so on.
CompileError: The WebAssembly.CompileError object indicates an error during WebAssembly decoding or validation.
CpuFeature: The nomenclature is inspired by the cpuid crate. The list of supported features was initially retrieved from cranelift-native.
DeserializeError: The Deserialize error can occur when loading a compiled Module from a binary.
ExportError: The ExportError can happen when trying to get a specific export Extern from the Instance exports.
ExportIndex: An entity to export.
Extern: An Extern is the runtime representation of an entity that can be imported or exported.
ExternType: A list of all possible types which can be externally referenced from a WebAssembly module.
GlobalInit: Globals are initialized via the const operators or by referring to another import.
InstantiationError: An error while instantiating a module.
IoCompileError: IO Error on a Module Compilation
LinkError: The WebAssembly.LinkError object indicates an error during module instantiation (besides traps from the start function).
MemoryAccessError: Error for invalid Memory access.
MemoryError: Error type describing things that can go wrong when operating on Wasm Memories.
Mutability: Indicator of whether a global is mutable or not
OnCalledAction: After the stack is unwound via asyncify what should the call loop do next
OperatingSystem: The “operating system” field, which sometimes implies an environment, and sometimes isn’t an actual operating system.
ParseCpuFeatureError: The error that can happen while parsing a str to retrieve a CpuFeature.
SerializeError: The Serialize error can occur when serializing a compiled Module into a binary.
Type: A list of all possible value types in WebAssembly.
Value: WebAssembly computations manipulate values of basic value types:
WasmError: A WebAssembly translation error.

Constants§

HOST: The Triple of the current host.
VERSION: Version number of this crate.
WASM_MAX_PAGES: The number of pages we can have before we run out of byte index space.
WASM_MIN_PAGES: The minimum number of pages allowed.
WASM_PAGE_SIZE: WebAssembly page sizes are fixed to be 64KiB. Note: large page support may be added in an opt-in manner in the future.

Traits§

AsEngineRef: Helper trait for a value that is convertible to a EngineRef.
AsStoreMut: Helper trait for a value that is convertible to a StoreMut.
AsStoreRef: Helper trait for a value that is convertible to a StoreRef.
Exportable: This trait is used to mark types as gettable from an Instance.
FromToNativeWasmType: A trait to convert a Rust value to a WasmNativeType value, or to convert WasmNativeType value to a Rust value.
HostFunction: The HostFunction trait represents the set of functions that can be used as host function. To uphold this statement, it is necessary for a function to be transformed into a VMFunctionCallback.
IntoBytes: Convert binary data into bytes::Bytes.
MemorySize: Trait for the Memory32 and Memory64 marker types.
NativeWasmTypeInto: NativeWasmTypeInto performs conversions from and into NativeWasmType types with a context.
Tunables: An engine delegates the creation of memories, tables, and globals to a foreign implementor of this trait.
ValueType: Trait for a Value type. A Value type is a type that is always valid and may be safely copied.
WasmTypeList: The WasmTypeList trait represents a tuple (list) of Wasm typed values. It is used to get low-level representation of such a tuple.

Functions§

is_wasm: Check if the provided bytes are wasm-like
wat2wasm: Parses in-memory bytes as either the WebAssembly Text format, or a binary WebAssembly module.

Type Aliases§

OnCalledHandler: Call handler for a store.
TrapHandlerFn: Function which may handle custom signals while processing traps.
WasmPtr64: Alias for `WasmPtr<T, Memory64>.
WasmResult: A convenient alias for a Result that uses WasmError as the error type.

Derive Macros§

ValueType

Crate wasmerCopy item path