wasmtime_wasi_io/
lib.rs

1//! # Wasmtime's wasi-io Implementation
2//!
3//! This crate provides a Wasmtime host implementation of the WASI 0.2 (aka
4//! WASIp2 aka Preview 2) wasi-io package. The host implementation is
5//! abstract: it is exposed as a set of traits which other crates provide
6//! impls of.
7//!
8//! The wasi-io package is the foundation which defines how WASI programs
9//! interact with the scheduler. It provides the `pollable`, `input-stream`,
10//! and `output-stream` Component Model resources, which other packages
11//! (including wasi-filesystem, wasi-sockets, wasi-cli, and wasi-http)
12//! expose as the standard way to wait for readiness, and asynchronously read
13//! and write to streams.
14//!
15//! This crate is designed to have no unnecessary dependencies and, in
16//! particular, to be #![no_std]. For an example no_std embedding, see
17//! [`/examples/min-platform`](https://github.com/bytecodealliance/wasmtime/tree/main/examples/min-platform)
18//! at the root of the wasmtime repo.
19
20#![no_std]
21
22extern crate alloc;
23#[cfg(feature = "std")]
24#[macro_use]
25extern crate std;
26
27pub mod bindings;
28mod impls;
29pub mod poll;
30pub mod streams;
31
32#[doc(no_inline)]
33pub use async_trait::async_trait;
34
35#[doc(no_inline)]
36pub use ::bytes;
37
38use alloc::boxed::Box;
39use wasmtime::component::{HasData, ResourceTable};
40
41/// A trait which provides access to the [`ResourceTable`] inside the
42/// embedder's `T` of [`Store<T>`][`Store`].
43///
44/// This crate's WASI Host implementations depend on the contents of
45/// [`ResourceTable`]. The `T` type [`Store<T>`][`Store`] is defined in each
46/// embedding of Wasmtime. These implementations is connected to the
47/// [`Linker<T>`][`Linker`] by the
48/// [`add_to_linker_async`] function.
49///
50/// # Example
51///
52/// ```
53/// use wasmtime::{Config, Engine};
54/// use wasmtime::component::{ResourceTable, Linker};
55/// use wasmtime_wasi_io::{IoView, add_to_linker_async};
56///
57/// struct MyState {
58///     table: ResourceTable,
59/// }
60///
61/// impl IoView for MyState {
62///     fn table(&mut self) -> &mut ResourceTable { &mut self.table }
63/// }
64/// let mut config = Config::new();
65/// config.async_support(true);
66/// let engine = Engine::new(&config).unwrap();
67/// let mut linker: Linker<MyState> = Linker::new(&engine);
68/// add_to_linker_async(&mut linker).unwrap();
69/// ```
70/// [`Store`]: wasmtime::Store
71/// [`Linker`]: wasmtime::component::Linker
72/// [`ResourceTable`]: wasmtime::component::ResourceTable
73///
74pub trait IoView {
75    /// Yields mutable access to the internal resource management that this
76    /// context contains.
77    ///
78    /// Embedders can add custom resources to this table as well to give
79    /// resources to wasm as well.
80    fn table(&mut self) -> &mut ResourceTable;
81}
82
83impl<T: ?Sized + IoView> IoView for &mut T {
84    fn table(&mut self) -> &mut ResourceTable {
85        T::table(self)
86    }
87}
88impl<T: ?Sized + IoView> IoView for Box<T> {
89    fn table(&mut self) -> &mut ResourceTable {
90        T::table(self)
91    }
92}
93
94/// Add the wasi-io host implementation from this crate into the `linker`
95/// provided.
96///
97/// This function will add the `async` variant of all interfaces into the
98/// [`Linker`] provided. By `async` this means that this function is only
99/// compatible with [`Config::async_support(true)`][async]. For embeddings
100/// with async support disabled, you'll need to use other crates, such as the
101/// [`wasmtime-wasi`] crate, which provides an [`add_to_linker_sync`] that
102/// includes an appropriate wasi-io implementation based on this crate's.
103///
104/// This function will add all interfaces implemented by this crate to the
105/// [`Linker`], which corresponds to the `wasi:io/imports` world supported by
106/// this crate.
107///
108/// [async]: wasmtime::Config::async_support
109/// [`Linker`]: wasmtime::component::Linker
110/// [`wasmtime-wasi`]: https://crates.io/crates/wasmtime-wasi
111/// [`add_to_linker_sync`]: https://docs.rs/wasmtime-wasi/latest/wasmtime_wasi/fn.add_to_linker_sync.html
112///
113///
114/// # Example
115///
116/// ```
117/// use wasmtime::{Engine, Result, Store, Config};
118/// use wasmtime::component::{ResourceTable, Linker};
119/// use wasmtime_wasi_io::IoView;
120///
121/// fn main() -> Result<()> {
122///     let mut config = Config::new();
123///     config.async_support(true);
124///     let engine = Engine::new(&config)?;
125///
126///     let mut linker = Linker::<MyState>::new(&engine);
127///     wasmtime_wasi_io::add_to_linker_async(&mut linker)?;
128///     // ... add any further functionality to `linker` if desired ...
129///
130///     let mut store = Store::new(
131///         &engine,
132///         MyState {
133///             table: ResourceTable::new(),
134///         },
135///     );
136///
137///     // ... use `linker` to instantiate within `store` ...
138///
139///     Ok(())
140/// }
141///
142/// struct MyState {
143///     table: ResourceTable,
144/// }
145///
146/// impl IoView for MyState {
147///     fn table(&mut self) -> &mut ResourceTable { &mut self.table }
148/// }
149/// ```
150pub fn add_to_linker_async<T: IoView + Send + 'static>(
151    l: &mut wasmtime::component::Linker<T>,
152) -> wasmtime::Result<()> {
153    crate::bindings::wasi::io::error::add_to_linker::<T, WasiIo>(l, T::table)?;
154    crate::bindings::wasi::io::poll::add_to_linker::<T, WasiIo>(l, T::table)?;
155    crate::bindings::wasi::io::streams::add_to_linker::<T, WasiIo>(l, T::table)?;
156    Ok(())
157}
158
159struct WasiIo;
160
161impl HasData for WasiIo {
162    type Data<'a> = &'a mut ResourceTable;
163}
wasmtime_wasi_io/lib.rs

wasmtime_wasi_io/
lib.rs
