From 58aa98ac8e3bc66c52e96fa1e5237795199d2355 Mon Sep 17 00:00:00 2001 From: Pat Hickey Date: Mon, 1 Feb 2021 18:07:05 -0800 Subject: [PATCH] cap-std-sync docs --- crates/wasi-common/cap-std-sync/src/lib.rs | 29 ++++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/crates/wasi-common/cap-std-sync/src/lib.rs b/crates/wasi-common/cap-std-sync/src/lib.rs index 2661b701d0..fe38951296 100644 --- a/crates/wasi-common/cap-std-sync/src/lib.rs +++ b/crates/wasi-common/cap-std-sync/src/lib.rs @@ -1,3 +1,32 @@ +//! The `wasi-cap-std-sync` crate provides impl of `WasiFile` and `WasiDir` in +//! terms of `cap_std::fs::{File, Dir}`. These types provide sandboxed access +//! to the local filesystem on both Unix and Windows. +//! +//! All syscalls are hidden behind the `cap-std` hierarchy, with the lone +//! exception of the `sched` implementation, which is provided for both unix +//! and windows in separate modules. +//! +//! Any `wasi_common::{WasiCtx, WasiCtxBuilder}` is interoperable with the +//! `wasi-cap-std-sync` crate. However, for convenience, `wasi-cap-std-sync` +//! provides its own `WasiCtxBuilder` that hooks up to all of the crate's +//! components, i.e. it fills in all of the arguments to +//! `WasiCtx::builder(...)`, presents `preopen_dir` in terms of +//! `cap_std::fs::Dir`, and provides convenience methods for inheriting the +//! parent process's stdio, args, and env. +//! +//! The only place we expect to run into long-term compatibility issues +//! between `wasi-cap-std-sync` and the other impl crates that will come later +//! is in the `Sched` abstraction. Once we can build an async scheduler based +//! on Rust `Future`s, async impls will be able to interoperate, but the +//! synchronous scheduler depends on downcasting the `WasiFile` type down to +//! concrete types it knows about (which in turn impl `AsRawFd` for passing to +//! unix `poll`, or the analogous traits on windows). +//! +//! Why is this impl suffixed with `-sync`? Because `async` is coming soon! +//! The async impl may end up depending on tokio or other relatively heavy +//! deps, so we will retain a sync implementation so that wasi-common users +//! have an option of not pulling in an async runtime. + pub mod clocks; pub mod dir; pub mod file;