126 releases (77 stable)
27.0.0 | Nov 20, 2024 |
---|---|
26.0.1 | Nov 5, 2024 |
26.0.0 | Oct 22, 2024 |
25.0.3 | Nov 5, 2024 |
0.8.0 | Nov 20, 2019 |
#957 in WebAssembly
83,497 downloads per month
Used in 175 crates
(87 directly)
3.5MB
54K
SLoC
Crate defining the Wasi
type for Wasmtime, which represents a WASI
instance which may be added to a linker.
lib.rs
:
Wasmtime's WASI Implementation
This crate 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.
For components and WASIp2, continue reading below. For WASIp1 and core
modules, see the preview1
module documentation.
WASIp2 interfaces
This crate contains implementations of the following interfaces:
wasi:cli/environment
wasi:cli/exit
wasi:cli/stderr
wasi:cli/stdin
wasi:cli/stdout
wasi:cli/terminal-input
wasi:cli/terminal-output
wasi:cli/terminal-stderr
wasi:cli/terminal-stdin
wasi:cli/terminal-stdout
wasi:clocks/monotonic-clock
wasi:clocks/wall-clock
wasi:filesystem/preopens
wasi:filesystem/types
wasi:io/error
wasi:io/poll
wasi:io/streams
wasi:random/insecure-seed
wasi:random/insecure
wasi:random/random
wasi:sockets/instance-network
wasi:sockets/ip-name-lookup
wasi:sockets/network
wasi:sockets/tcp-create-socket
wasi:sockets/tcp
wasi:sockets/udp-create-socket
wasi:sockets/udp
All traits are implemented in terms of a WasiView
trait which provides
basic access to WasiCtx
, configuration for WASI, and ResourceTable
,
the state for all host-defined component model resources.
Generated Bindings
This crate uses wasmtime::component::bindgen!
to generate bindings for
all WASI interfaces. Raw bindings are available in the bindings
module
of this crate. Downstream users can either implement these traits themselves
or you can use the built-in implementations in this crate for
WasiImpl<T: WasiView>
.
The WasiView
trait
This crate'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>
. All implementations of
traits look like:
impl<T: WasiView> bindings::wasi::Host for WasiImpl<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>
. Next you'll implement the WasiView
trait for T
. Somewhere
within T
you'll store:
WasiCtx
- created throughWasiCtxBuilder
.ResourceTable
- created through default constructors.
These two fields are then accessed through the methods of WasiView
.
Async and Sync
Many WASI functions are not blocking from WebAssembly's point of view, but
for those that do they're provided in two flavors: asynchronous and
synchronous. Which version you will use depends on how
Config::async_support
is set.
- For non-async users (the default of
Config
), useadd_to_linker_sync
. - For async users, use
add_to_linker_async
.
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 areasync
bindings::sync
- blocking interfaces have synchronous versions here.
Crate-specific traits
This crate'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 crate.
-
HostInputStream
andHostOutputStream
- these are the host traits behind the WASIinput-stream
andoutput-stream
types in thewasi:io/streams
interface. These enable embedders to build their own custom stream and insert them into aResourceTable
to be used from wasm. -
Subscribe
- this trait enables building arbitrary logic to get hooked into apollable
resource fromwasi:io/poll
. A pollable resource is created through thesubscribe
function. -
HostWallClock
andHostMonotonicClock
are used in conjunction withWasiCtxBuilder::wall_clock
andWasiCtxBuilder::monotonic_clock
if the defaults host's clock should not be used. -
StdinStream
andStdoutStream
are used to provide custom stdin/stdout streams if they're not inherited (or null, which is the default).
These traits enable embedders to customize small portions of WASI interfaces provided while still providing all other interfaces.
Examples
Usage of this crate is done through a few steps to get everything hooked up:
- First implement
WasiView
for your type which is theT
inStore<T>
. - Add WASI interfaces to a
wasmtime::component::Linker<T>
. This is either done through top-level functions likeadd_to_linker_sync
or through individualadd_to_linker
functions in generated bindings throughout this crate. - Create a
WasiCtx
for eachStore<T>
throughWasiCtxBuilder
. 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). - Use the previous
Linker<T>
to instantiate aComponent
within aStore<T>
.
For examples see each of WasiView
, WasiCtx
, WasiCtxBuilder
,
add_to_linker_sync
, and bindings::Command
.
Dependencies
~27–41MB
~769K SLoC