[][src]Crate wasmtime

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:

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.

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, WasiCtx};

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, WasiCtx::new(std::env::args())?);
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.

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.

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.

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.

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.