Skip to main content

Module p2

wasmtime_wasi

Module p2 

Source
Expand description

§Wasmtime’s WASIp2 Implementation

This module provides a Wasmtime host implementation of WASI 0.2 (aka WASIp2 aka Preview 2) and WASI 0.1 (aka WASIp1 aka Preview 1). WASI is implemented with the Rust crates tokio and cap-std primarily, meaning that operations are implemented in terms of their native platform equivalents by default.

§WASIp2 interfaces

This module contains implementations of the following interfaces:

Most traits are implemented for WasiCtxView trait which provides access to WasiCtx and ResourceTable, which defines the configuration for WASI and handle state. The WasiView trait is used to acquire and construct a WasiCtxView.

The wasmtime-wasi-io crate contains implementations of the following interfaces, and this module reuses those implementations:

These traits are implemented directly for ResourceTable. All aspects of wasmtime-wasi-io that are used by this module are re-exported. Unless you are implementing other host functionality that needs to interact with the WASI scheduler and don’t want to use other functionality provided by wasmtime-wasi, you don’t need to take a direct dependency on wasmtime-wasi-io.

§Generated Bindings

This module uses wasmtime::component::bindgen! to generate bindings for all WASI interfaces. Raw bindings are available in the bindings submodule of this module. Downstream users can either implement these traits themselves or you can use the built-in implementations in this module for WasiImpl<T: WasiView>.

§The WasiView trait

This module’s implementation of WASI is done in terms of an implementation of WasiView. This trait provides a “view” into WASI-related state that is contained within a Store<T>.

For all of the generated bindings in this module (Host traits), implementations are provided looking like:

impl bindings::wasi::Host for WasiCtxView<'_> {
    // ...
}

where the WasiCtxView type comes from WasiView::ctx for the type contained within the Store<T>. The add_to_linker_sync and add_to_linker_async function then require that T: WasiView with Linker<T>.

To implement the WasiView trait you will first select a T to put in Store<T> (typically, by defining your own struct). Somewhere within T you’ll store:

You’ll then write an implementation of the WasiView trait to access those items in your T. For example:

use wasmtime::component::ResourceTable;
use wasmtime_wasi::{WasiCtx, WasiCtxView, WasiView};

struct MyCtx {
    table: ResourceTable,
    wasi: WasiCtx,
}

impl WasiView for MyCtx {
    fn ctx(&mut self) -> WasiCtxView<'_> {
        WasiCtxView { ctx: &mut self.wasi, table: &mut self.table }
    }
}

§Async and Sync

All WASIp2 functions are blocking from WebAssembly’s point of view: a WebAssembly call into these functions returns only when they are complete.

This module provides an implementation of those functions in the host, where for some functions, it is appropriate to implement them using async Rust and the Tokio executor. The host implementation still blocks WebAssembly, but it does not block the host’s thread. Synchronous wrappers are also provided for all async implementations, which create a private Tokio executor.

Users can choose between these modes of implementation using variants of the add_to_linker functions:

Note that bindings are generated once for async and once for sync. Most interfaces do not change, however, so only interfaces with blocking functions have bindings generated twice. Bindings are organized as:

  • bindings - default location of all bindings, blocking functions are async
  • bindings::sync - blocking interfaces have synchronous versions here.

§Module-specific traits

This module’s default implementation of WASI bindings to native primitives for the platform that it is compiled for. For example opening a TCP socket uses the native platform to open a TCP socket (so long as WasiCtxBuilder allows it). There are a few important traits, however, that are specific to this module.

These traits enable embedders to customize small portions of WASI interfaces provided while still providing all other interfaces.

§Examples

Usage of this module is done through a few steps to get everything hooked up:

  1. First implement WasiView for your type which is the T in Store<T>.
  2. Add WASI interfaces to a wasmtime::component::Linker<T>. This is either done through top-level functions like add_to_linker_sync or through individual add_to_linker functions in generated bindings throughout this module.
  3. Create a WasiCtx for each Store<T> through WasiCtxBuilder. Each WASI context is “null” or “empty” by default, so items must be explicitly added to get accessed by wasm (such as env vars or program arguments).
  4. Use the previous Linker<T> to instantiate a Component within a Store<T>.

For examples see each of WasiView, WasiCtx, WasiCtxBuilder, add_to_linker_sync, and bindings::Command.

Modules§

bindings
Auto-generated bindings for WASI interfaces.
pipe
Virtual pipes.

Structs§

DynPollable
The host representation of the wasi:io/poll.pollable resource.
Network
ReaddirIterator

Enums§

IsATTY
StreamError

Traits§

InputStream
Host trait for implementing the wasi:io/streams.input-stream resource: A bytestream which can be read from.
OutputStream
Host trait for implementing the wasi:io/streams.output-stream resource: A bytestream which can be written to.
Pollable
The trait used to implement DynPollable to create a pollable resource in wasi:io/poll.

Functions§

add_to_linker_async
Add all WASI interfaces from this crate into the linker provided.
add_to_linker_proxy_interfaces_async
Same as add_to_linker_async except that this only adds interfaces present in the wasi:http/proxy world.
add_to_linker_sync
Add all WASI interfaces from this crate into the linker provided.
add_to_linker_with_options_async
Similar to add_to_linker_async, but with the ability to enable unstable features.
add_to_linker_with_options_sync
Similar to add_to_linker_sync, but with the ability to enable unstable features.
subscribe
Creates a wasi:io/poll.pollable resource which is subscribed to the provided resource.

Type Aliases§

DynFuture
DynInputStream
DynOutputStream
FsError
FsResult
IoError
Representation of the error resource type in the wasi:io/error interface.
MakeFuture
SocketError
SocketResult
StreamResult