cap-std-sync docs

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;