From 0ef691b74e935f38dd5aa6de9e8146f5eb90385c Mon Sep 17 00:00:00 2001 From: Pat Hickey Date: Mon, 1 Feb 2021 18:01:47 -0800 Subject: [PATCH] rustdocs!! --- crates/wasi-common/src/lib.rs | 52 +++++++++++++++++++++++++ crates/wasi-common/src/snapshots/mod.rs | 25 ++++++++++++ 2 files changed, 77 insertions(+) diff --git a/crates/wasi-common/src/lib.rs b/crates/wasi-common/src/lib.rs index 2d0f50a5f4..4575b423b6 100644 --- a/crates/wasi-common/src/lib.rs +++ b/crates/wasi-common/src/lib.rs @@ -1,3 +1,55 @@ +//! ## The `WasiFile` and `WasiDir` traits +//! +//! The WASI specification only defines one `handle` type, `fd`, on which all +//! operations on both files and directories (aka dirfds) are defined. We +//! believe this is a design mistake, and are architecting wasi-common to make +//! this straightforward to correct in future snapshots of WASI. Wasi-common +//! internally treats files and directories as two distinct resource types in +//! the table - `Box` and `Box`. The snapshot 0 and +//! 1 interfaces via `fd` will attempt to downcast a table element to one or +//! both of these interfaces depending on what is appropriate - e.g. +//! `fd_close` operates on both files and directories, `fd_read` only operates +//! on files, and `fd_readdir` only operates on directories. + +//! The `WasiFile` and `WasiDir` traits are defined by `wasi-common` in terms +//! of types defined directly in the crate's source code (I decided it should +//! NOT those generated by the `wiggle` proc macros, see snapshot architecture +//! below), as well as the `cap_std::time` family of types. And, importantly, +//! `wasi-common` itself provides no implementation of `WasiDir`, and only two +//! trivial implementations of `WasiFile` on the `crate::pipe::{ReadPipe, +//! WritePipe}` types, which in turn just delegate to `std::io::{Read, +//! Write}`. In order for `wasi-common` to access the local filesystem at all, +//! you need to provide `WasiFile` and `WasiDir` impls through either the new +//! `wasi-cap-std-sync` crate found at `crates/wasi-common/cap-std-sync` - see +//! the section on that crate below - or by providing your own implementation +//! from elsewhere. +//! +//! This design makes it possible for `wasi-common` embedders to statically +//! reason about access to the local filesystem by examining what impls are +//! linked into an application. We found that this separation of concerns also +//! makes it pretty enjoyable to write alternative implementations, e.g. a +//! virtual filesystem (which will land in a future PR). +//! +//! ## Traits for the rest of WASI's features +//! +//! Other aspects of a WASI implementation are not yet considered resources +//! and accessed by `handle`. We plan to correct this design deficiency in +//! WASI in the future, but for now we have designed the following traits to +//! provide embedders with the same sort of implementation flexibility they +//! get with WasiFile/WasiDir: +//! +//! * Timekeeping: `WasiSystemClock` and `WasiMonotonicClock` provide the two +//! interfaces for a clock. `WasiSystemClock` represents time as a +//! `cap_std::time::SystemTime`, and `WasiMonotonicClock` represents time as +//! `cap_std::time::Instant`. * Randomness: we re-use the `cap_rand::RngCore` +//! trait to represent a randomness source. A trivial `Deterministic` impl is +//! provided. * Scheduling: The `WasiSched` trait abstracts over the +//! `sched_yield` and `poll_oneoff` functions. +//! +//! Users can provide implementations of each of these interfaces to the +//! `WasiCtx::builder(...)` function. The +//! `wasi_cap_std_sync::WasiCtxBuilder::new()` function uses this public +//! interface to plug in its own implementations of each of these resources. pub mod clocks; mod ctx; pub mod dir; diff --git a/crates/wasi-common/src/snapshots/mod.rs b/crates/wasi-common/src/snapshots/mod.rs index 85eb4cea32..f25c8a3b09 100644 --- a/crates/wasi-common/src/snapshots/mod.rs +++ b/crates/wasi-common/src/snapshots/mod.rs @@ -1,2 +1,27 @@ +//! One goal of `wasi-common` is for multiple WASI snapshots to provide an +//! interface to the same underlying `crate::WasiCtx`. This provides us a path +//! to evolve WASI by allowing the same WASI Command to import functions from +//! different snapshots - e.g. the user could use Rust's `std` which imports +//! snapshot 1, but also depend directly on the `wasi` crate which imports +//! some future snapshot 2. Right now, this amounts to supporting snapshot 1 +//! and "snapshot 0" aka wasi_unstable at once. +//! +//! The architectural rules for snapshots are: +//! +//! * Snapshots are arranged into modules under `crate::snapshots::`. +//! +//! * Each snapshot should invoke `wiggle::from_witx!` with `ctx: +//! crate::WasiCtx` in its module, and impl all of the required traits. +//! +//!* Snapshots can be implemented in terms of other snapshots. For example, +//! snapshot 0 is mostly implemented by calling the snapshot 1 implementation, +//! and converting its own types back and forth with the snapshot 1 types. In a +//! few cases, that is not feasible, so snapshot 0 carries its own +//! implementations in terms of the `WasiFile` and `WasiSched` traits. +//! +//! * Snapshots can be implemented in terms of the `Wasi*` traits given by +//! `WasiCtx`. No further downcasting via the `as_any` escape hatch is +//! permitted. + pub mod preview_0; pub mod preview_1;