Crate wasmtime[][src]

Wasmtime’s embedding API

This crate contains an API used to interact with WebAssembly modules. For example you can compile modules, instantiate them, call them, etc. As an embedder of WebAssembly you can also provide WebAssembly modules functionality from the host by creating host-defined functions, memories, globals, etc, which can do things that WebAssembly cannot (such as print to the screen).

The wasmtime crate draws inspiration from a number of sources, including the JS WebAssembly API as well as the proposed C API. As with all other Rust code you’re guaranteed that programs will be safe (not have undefined behavior or segfault) so long as you don’t use unsafe in your own program. With wasmtime you can easily and conveniently embed a WebAssembly runtime with confidence that the WebAssembly is safely sandboxed.

An example of using Wasmtime looks like:

use anyhow::Result;
use wasmtime::*;

fn main() -> Result<()> {
    // All wasm objects operate within the context of a "store"
    let store = Store::default();

    // Modules can be compiled through either the text or binary format
    let wat = r#"
        (module
            (import "" "" (func $host_hello (param i32)))

            (func (export "hello")
                i32.const 3
                call $host_hello)
        )
    "#;
    let module = Module::new(store.engine(), wat)?;

    // Host functions can be defined which take/return wasm values and
    // execute arbitrary code on the host.
    let host_hello = Func::wrap(&store, |param: i32| {
        println!("Got {} from WebAssembly", param);
    });

    // Instantiation of a module requires specifying its imports and then
    // afterwards we can fetch exports by name, as well as asserting the
    // type signature of the function with `get0`.
    let instance = Instance::new(&store, &module, &[host_hello.into()])?;
    let hello = instance
        .get_func("hello")
        .ok_or(anyhow::format_err!("failed to find `hello` function export"))?
        .get0::<()>()?;

    // And finally we can call the wasm as if it were a Rust function!
    hello()?;

    Ok(())
}

Core Concepts

There are a number of core types and concepts that are important to be aware of when using the wasmtime crate:

  • Reference counting - almost all objects in this API are reference counted. Most of the time when and object is cloned you’re just bumping a reference count. For example when you clone an Instance that is a cheap operation, it doesn’t create an entirely new instance.

  • Store - all WebAssembly object and host values will be “connected” to a store. A Store is not threadsafe which means that itself and all objects connected to it are pinned to a single thread (this happens automatically through a lack of the Send and Sync traits). Similarly wasmtime does not have a garbage collector so anything created within a Store will not be deallocated until all references have gone away. See the Store documentation for more information.

  • Module - a compiled WebAssembly module. This structure represents in-memory JIT code which is ready to execute after being instantiated. It’s often important to cache instances of a Module because creation (compilation) can be expensive. Note that Module is safe to share across threads.

  • Instance - an instantiated WebAssembly module. An instance is where you can actually acquire a Func from, for example, to call. Each Instance, like all other Store-connected objects, cannot be sent across threads.

There are other important types within the wasmtime crate but it’s crucial to be familiar with the above types! Be sure to browse the API documentation to get a feeling for what other functionality is offered by this crate.

Example Architecture

To better understand how Wasmtime types interact with each other let’s walk through, at a high-level, an example of how you might use WebAssembly. In our use case let’s say we have a web server where we’d like to run some custom WebAssembly on each request. To ensure requests are isolated from each other, though, we’ll be creating a new Instance for each request.

When the server starts, we’ll start off by creating an Engine (and maybe tweaking Config settings if necessary). This Engine will be the only engine for the lifetime of the server itself.

Next, we can compile our WebAssembly. You’d create a Module through the Module::new API. This will generate JIT code and perform expensive compilation tasks up-front.

After that setup, the server starts up as usual and is ready to receive requests. Upon receiving a request you’d then create a Store with Store::new referring to the original Engine. Using your Module from before you’d then call Instance::new to instantiate our module for the request. Both of these operations are designed to be as cheap as possible.

With an Instance you can then invoke various exports and interact with the WebAssembly module. Once the request is finished the Store, Instance, and all other items loaded are dropped and everything will be deallocated. Note that it’s crucial to create a Store-per-request to ensure that memory usage doesn’t balloon accidentally by keeping a Store alive indefinitely.

Advanced Linking

Often WebAssembly modules are not entirely self-isolated. They might refer to quite a few pieces of host functionality, WASI, or maybe even a number of other wasm modules. To help juggling all this together this crate provides a Linker type which serves as an abstraction to assist in instantiating a module. The Linker type also transparently handles Commands and Reactors as defined by WASI.

WASI

The wasmtime crate does not natively provide support for WASI, but you can use the wasmtime-wasi crate for that purpose. With wasmtime-wasi you can create a “wasi instance” and then add all of its items into a Linker, which can then be used to instantiate a Module that uses WASI.

Crate Features

The wasmtime crate comes with a number of compile-time features that can be used to customize what features it supports. Some of these features are just internal details, but some affect the public API of the wasmtime crate. Be sure to check the API you’re using to see if any crate features are enabled.

  • cache - Enabled by default, this feature adds support for wasmtime to perform internal caching of modules in a global location. This must still be enabled explicitly through Config::cache_config_load or Config::cache_config_load_default.

  • wat - Enabled by default, this feature adds support for accepting the text format of WebAssembly in Module::new. The text format will be automatically recognized and translated to binary when compiling a module.

  • parallel-compilation - Enabled by default, this feature enables support for compiling functions of a module in parallel with rayon.

  • async - Enabled by default, this feature enables APIs and runtime support for defining asynchronous host functions and calling WebAssembly asynchronously.

  • jitdump - Enabled by default, this feature compiles in support for the jitdump runtime profilng format. The profiler can be selected with Config::profiler.

  • vtune - Not enabled by default, this feature compiles in support for supporting VTune profiling of JIT code.

Examples

In addition to the examples below be sure to check out the online embedding documentation as well as the online list of examples

An example of using WASI looks like:

use wasmtime_wasi::Wasi;
use wasi_cap_std_sync::WasiCtxBuilder;

let store = Store::default();
let mut linker = Linker::new(&store);

// Create an instance of `Wasi` which contains a `WasiCtx`. Note that
// `WasiCtx` provides a number of ways to configure what the target program
// will have access to.
let wasi = Wasi::new(&store, WasiCtxBuilder::new().inherit_stdio().build()?);
wasi.add_to_linker(&mut linker)?;

// Instantiate our module with the imports we've created, and run it.
let module = Module::from_file(store.engine(), "foo.wasm")?;
let instance = linker.instantiate(&module)?;
// ...

An example of reading a string from a wasm module:

use std::str;

let store = Store::default();
let log_str = Func::wrap(&store, |caller: Caller<'_>, ptr: i32, len: i32| {
    let mem = match caller.get_export("memory") {
        Some(Extern::Memory(mem)) => mem,
        _ => return Err(Trap::new("failed to find host memory")),
    };

    // We're reading raw wasm memory here so we need `unsafe`. Note
    // though that this should be safe because we don't reenter wasm
    // while we're reading wasm memory, nor should we clash with
    // any other memory accessors (assuming they're well-behaved
    // too).
    unsafe {
        let data = mem.data_unchecked()
            .get(ptr as u32 as usize..)
            .and_then(|arr| arr.get(..len as u32 as usize));
        let string = match data {
            Some(data) => match str::from_utf8(data) {
                Ok(s) => s,
                Err(_) => return Err(Trap::new("invalid utf-8")),
            },
            None => return Err(Trap::new("pointer/length out of bounds")),
        };
        assert_eq!(string, "Hello, world!");
        println!("{}", string);
    }
    Ok(())
});
let module = Module::new(
    store.engine(),
    r#"
        (module
            (import "" "" (func $log_str (param i32 i32)))
            (func (export "foo")
                i32.const 4   ;; ptr
                i32.const 13  ;; len
                call $log_str)
            (memory (export "memory") 1)
            (data (i32.const 4) "Hello, world!"))
    "#,
)?;
let instance = Instance::new(&store, &module, &[log_str.into()])?;
let foo = instance.get_func("foo").unwrap().get0::<()>()?;
foo()?;

Modules

unix

Unix-specific extension for the wasmtime crate.

Structs

Caller

A structure representing the caller’s context when creating a function via Func::wrap.

Config

Global configuration options used to create an Engine and customize its behavior.

Engine

An Engine which is a global context for compilation and management of wasm modules.

Export

An exported WebAssembly value.

ExportType

A descriptor for an exported WebAssembly value.

ExternRef

Represents an opaque reference to any data within WebAssembly.

FrameInfo

Description of a frame in a backtrace for a Trap.

FrameSymbol

Debug information for a symbol that is attached to a FrameInfo.

Func

A WebAssembly function which can be called.

FuncType

A descriptor for a function in a WebAssembly module.

Global

A WebAssembly global value which can be read and written to.

GlobalType

A WebAssembly global descriptor.

ImportType

A descriptor for an imported value into a wasm module.

Instance

An instantiated WebAssembly module.

InstanceType

A descriptor for a WebAssembly instance type.

InterruptHandle

A threadsafe handle used to interrupt instances executing within a particular Store.

Limits

Limits of tables/memories where the units of the limits are defined by the table/memory types.

Linker

Structure used to link wasm modules/instances together.

Memory

A WebAssembly linear memory.

MemoryAccessError

Error for out of bounds Memory access.

MemoryType

A descriptor for a WebAssembly memory type.

Module

A compiled WebAssembly module, ready to be instantiated.

ModuleType

A descriptor for a WebAssembly module type.

Store

A Store is a collection of WebAssembly instances and host-defined items.

Table

A WebAssembly table, or an array of values.

TableType

A descriptor for a table in a WebAssembly module.

Trap

A struct representing an aborted instruction execution, with a message indicating the cause.

WasmCall

Returned future from the Func::get1_async family of methods, used to represent an asynchronous call into WebAssembly.

Enums

Extern

An external item to a WebAssembly module, or a list of what can possibly be exported from a wasm module.

ExternType

A list of all possible types which can be externally referenced from a WebAssembly module.

Mutability

Indicator of whether a global is mutable or not

OptLevel

Possible optimization levels for the Cranelift codegen backend.

ProfilingStrategy

Select which profiling technique to support.

Strategy

Possible Compilation strategies for a wasm module.

TrapCode

A trap code describing the reason for a trap.

Val

Possible runtime values that a WebAssembly module can either consume or produce.

ValType

A list of all possible value types in WebAssembly.

WasmBacktraceDetails

Select how wasm backtrace detailed information is handled.

Traits

IntoFunc

Internal trait implemented for all arguments that can be passed to Func::wrap.

LinearMemory

A linear memory. This trait provides an interface for raw memory buffers which are used by wasmtime, e.g. inside [‘Memory’]. Such buffers are in principle not thread safe. By implementing this trait together with MemoryCreator, one can supply wasmtime with custom allocated host managed memory.

MemoryCreator

A memory creator. Can be used to provide a memory creator to wasmtime which supplies host managed memory.

WasmRet

A trait implemented for types which can be returned from closures passed to Func::wrap and friends.

WasmTy

A trait implemented for types which can be arguments to closures passed to Func::wrap and friends.