wstd/
lib.rs

1#![allow(async_fn_in_trait)]
2#![warn(future_incompatible, unreachable_pub)]
3#![deny(unsafe_code)]
4//#![deny(missing_debug_implementations)]
5//#![warn(missing_docs)]
6//#![forbid(rustdoc::missing_doc_code_examples)]
7
8//! An async standard library for Wasm Components and WASI 0.2
9//!
10//! This is a minimal async standard library written exclusively to support Wasm
11//! Components. It exists primarily to enable people to write async-based
12//! applications in Rust before async-std, smol, or tokio land support for Wasm
13//! Components and WASI 0.2. Once those runtimes land support, it is recommended
14//! users switch to use those instead.
15//!
16//! # Examples
17//!
18//! **TCP echo server**
19//!
20//! ```rust,no_run
21#![doc = include_str!("../examples/tcp_echo_server.rs")]
22//! ```
23//!
24//! **HTTP Client**
25//!
26//! ```rust,ignore
27#![doc = include_str!("../tests/http_get.rs")]
28//! ```
29//!
30//! **HTTP Server**
31//!
32//! ```rust,no_run
33#![doc = include_str!("../examples/http_server.rs")]
34//! ```
35//!
36//! # Design Decisions
37//!
38//! This library is entirely self-contained. This means that it does not share
39//! any traits or types with any other async runtimes. This means we're trading
40//! in some compatibility for ease of maintenance. Because this library is not
41//! intended to be maintained in the long term, this seems like the right
42//! tradeoff to make.
43//!
44//! WASI 0.2 does not yet support multi-threading. For that reason this library
45//! does not provide any multi-threaded primitives, and is free to make liberal
46//! use of Async Functions in Traits since no `Send` bounds are required. This
47//! makes for a simpler end-user experience, again at the cost of some
48//! compatibility. Though ultimately we do believe that using Async Functions is
49//! the right foundation for the standard library abstractions - meaning we may
50//! be trading in backward-compatibility for forward-compatibility.
51//!
52//! This library also supports slightly more interfaces than the stdlib does.
53//! For example `wstd::rand` is a new module that provides access to random
54//! bytes. And `wstd::runtime` provides access to async runtime primitives.
55//! These are unique capabilities provided by WASI 0.2, and because this library
56//! is specific to that are exposed from here.
57
58pub mod future;
59#[macro_use]
60pub mod http;
61pub mod io;
62pub mod iter;
63pub mod net;
64pub mod rand;
65pub mod runtime;
66pub mod task;
67pub mod time;
68
69pub use wstd_macro::attr_macro_http_server as http_server;
70pub use wstd_macro::attr_macro_main as main;
71pub use wstd_macro::attr_macro_test as test;
72
73// Re-export the wasip2 crate for use only by `wstd-macro` macros. The proc
74// macros need to generate code that uses these definitions, but we don't want
75// to treat it as part of our public API with regards to semver, so we keep it
76// under `__internal` as well as doc(hidden) to indicate it is private.
77#[doc(hidden)]
78pub mod __internal {
79    pub use wasip2;
80}
81
82pub mod prelude {
83    pub use crate::future::FutureExt as _;
84    pub use crate::io::AsyncRead as _;
85    pub use crate::io::AsyncWrite as _;
86}
wstd/lib.rs

wstd/
lib.rs
