From cf21bca27ee36d1418105195412e41c66e701db0 Mon Sep 17 00:00:00 2001 From: Luke Wagner Date: Mon, 15 Jun 2026 15:42:58 -0500 Subject: [PATCH] Update README.md and other docs based on WASI 0.3 release --- README.md | 47 +++++++++++++++++++++++------------ design/mvp/Concurrency.md | 52 +++++++++++++++++++-------------------- design/mvp/Explainer.md | 32 +++++++++++++----------- design/mvp/Linking.md | 4 +-- design/mvp/WIT.md | 2 +- 5 files changed, 77 insertions(+), 60 deletions(-) diff --git a/README.md b/README.md index 9bcd9259..e2dce695 100644 --- a/README.md +++ b/README.md @@ -1,22 +1,35 @@ # Component Model design and specification -This repository is where the component model is being standardized. For a more +This repository is where the Component Model is being standardized. For a more user-focused explanation, take a look at the **[Component Model Documentation]**. -This repository contains the high-level [goals], [use cases], [design choices] -and [FAQ] of the Component Model as well as more-detailed, low-level explainer -docs describing the [IDL], [text format], [binary format], [concurrency model] -and [Canonical ABI]. +This repository contains: +* high-level [goals], [use cases], [design choices] and [FAQ] docs +* low-level [WIT], [text format], [binary format], [concurrency] and [ABI] docs +* a growing [WAST test suite] -In the future, this repository will additionally contain a [formal spec], -reference interpreter and test suite. +In the future, this repository will additionally contain a [formal spec] and a +reference interpreter. ## Milestones -The Component Model is currently being incrementally developed and stabilized -as part of [WASI Preview 2]. The subsequent [WASI Preview 3] milestone will be -primarily concerned with the addition of [async and thread support][Concurrency -Model]. +The Component Model is currently being developed incrementally as part of [WASI] +"Developer Preview" releases. The Component Model features enabled as part of a +WASI Developer Preview release are kept stable by producer and consumer tools so +that they can be used outside the browser in production settings to collect +real-world feedback. + +The current WASI Developer Preview releases are: +* 0.2.0: the first release based on the Component Model; includes + shared-nothing and shared-everything [linking], a variety of high-level + value types, `resource` types with handles, and [WIT]. +* 0.3.0: the first release with native [concurrency] support in the Component + Model and [WIT]; adds `async` functions, `stream`s and `future`s as + well as new [ABI] built-in functions (additions are marked by the πŸ”€ + emoji throughout the repo). + +Subsequent WASI Developer Preview releases will include other emoji-[gated +features] such as cooperative threads (🧡). ## Contributing @@ -30,13 +43,15 @@ To contribute to any of these repositories, see the Community Group's [Use Cases]: design/high-level/UseCases.md [Design Choices]: design/high-level/Choices.md [FAQ]: design/high-level/FAQ.md -[IDL]: design/mvp/WIT.md +[WIT]: design/mvp/WIT.md [Text Format]: design/mvp/Explainer.md [Binary Format]: design/mvp/Binary.md -[Concurrency Model]: design/mvp/Concurrency.md -[Canonical ABI]: design/mvp/CanonicalABI.md +[Concurrency]: design/mvp/Concurrency.md +[ABI]: design/mvp/CanonicalABI.md +[WAST test suite]: test/ [formal spec]: spec/ +[Linking]: design/mvp/Linking.md +[Gated Features]: design/mvp/Explainer.md#gated-features [W3C WebAssembly Community Group]: https://www.w3.org/community/webassembly/ [Contributing Guidelines]: https://webassembly.org/community/contributing/ -[WASI Preview 2]: https://github.com/WebAssembly/WASI/blob/main/docs/Preview2.md -[WASI Preview 3]: https://github.com/WebAssembly/WASI/blob/main/docs/Preview2.md#looking-forward-to-preview-3 +[WASI]: https://github.com/WebAssembly/WASI diff --git a/design/mvp/Concurrency.md b/design/mvp/Concurrency.md index 0d1cd472..44cb269d 100644 --- a/design/mvp/Concurrency.md +++ b/design/mvp/Concurrency.md @@ -1,9 +1,9 @@ # Concurrency Explainer -This document contains a high-level summary of the native concurrency support -added as part of [WASI Preview 3], providing background for understanding the -definitions in the [WIT], [AST explainer], [binary format] and [Canonical ABI -explainer] documents that are gated by the πŸ”€ (async) and 🧡 (threading) emojis. +This document contains a high-level summary of the native concurrency support, +providing background for understanding the definitions in the [WIT], [AST +explainer], [binary format] and [Canonical ABI explainer] documents that are +gated by the πŸ”€ (async) and 🧡 (threading) emojis. * [Goals](#goals) * [Summary](#summary) @@ -34,9 +34,9 @@ explainer] documents that are gated by the πŸ”€ (async) and 🧡 (threading) emo ## Goals -Refining the Component Model's high-level [goals](../high-level/Goals.md) and -[use cases](../high-level/UseCases.md), [WASI Preview 3] adds the following -concurrency-specific goals and use cases: +With the release of [WASI] 0.3, the following concurrency-specific goals and +use cases are added, refining the Component Model's high-level +[goals](../high-level/Goals.md) and [use cases](../high-level/UseCases.md): * Integrate with idiomatic source-language concurrency features including: * `async` functions in languages like C#, JS, Python, Rust and Swift @@ -92,7 +92,7 @@ invariant is necessary to allow non-`async` component exports to be called in synchronous contexts (like event listeners, callbacks, getters, setters and constructors). -The new async ABI can be used alongside or instead of the existing Preview 2 +The new async ABI can be used alongside or instead of the existing [WASI] 0.2 "sync ABI" to call or implement any `async`-typed functions. When *calling* an imported function via the async ABI, if the `async` callee [blocks](#blocking), control flow is returned immediately to the caller, and the callee continues @@ -108,7 +108,7 @@ can compile directly to components exporting `async` functions without having to be rewritten to use source-language concurrency mechanisms (like callbacks, `async`/`wait`, coroutines, etc). For example, traditional C programs with a `main()` and calls to `read()`, `write()` and `select()` can run without change -in the Preview 3 `wasi:cli/command` world, which exports `run: async func() -> +in the [WASI] 0.3 `wasi:cli/command` world, which exports `run: async func() -> result`. Thus, `async` in WIT does not require the same kind of transitive source-code changes as source-level `async` in languages like C#, Python, JS, Rust and Dart. @@ -911,9 +911,10 @@ the Component Model has [Component Invariant] #2. This is enforced by the [Canonical ABI](CanonicalABI.md#embedding) using strategically placed traps and boolean flags on component instances. -With Preview 3, a desirable outcome is that if our component imports `imp` and -exports `exp` as `async` functions, then the following JS code could run the -two `exp` calls concurrently just like if they were JS `async` functions: +With native concurrency support, what we'd naturally expect is that if our +component imports `imp` and exports `exp` as `async` functions, then the +following JS code could run the two `exp` calls concurrently, as if they were JS +`async` functions: ```js import source component from './component.wasm'; async function imp() { @@ -1003,7 +1004,7 @@ task" to which work can be dispatched (e.g., via the `setInterval()` or concurrency], these background tasks are new task tree roots (siblings to the roots created when component exports are called by the host). -As a Preview 3 follow-up [TODO](#TODO), component type definitions should be +As a post-0.3.0 follow-up [TODO](#TODO), component type definitions should be extended to allow an `async` effect that declares that component instantiation is allowed to [block](#blocking). This would be necessary to implement, e.g., JS [top-level `await`] or I/O in C++ constructors executing during `start`. @@ -1013,7 +1014,7 @@ JS [top-level `await`] or I/O in C++ constructors executing during `start`. At an ABI level, native async in the Component Model defines for every `async`-typed function a non-blocking core function signature that can be -used instead of or in addition to the existing (Preview-2-defined) synchronous +used instead of or in addition to the existing ([WASI] 0.2) synchronous core function signature. This non-blocking core function signature is intended to be called or implemented by generated bindings which then map the low-level core async protocol to the languages' higher-level native concurrency features. @@ -1406,7 +1407,7 @@ instance lifetimes are flexible in this manner and don't have an obvious end conventionally ends right after `main()` returns), the host still needs to understand the expectations of component authors to enable portability. -Before the addition of native concurrency support in Preview 3, a natural +Before the addition of native concurrency support in [WASI] 0.3, a natural expectation is that, in the absence of atypical scenarios like timeouts or quota exhaustion, a component author can expect that their component instance will not be abruptly terminated during the execution of contained Core WebAssembly code. @@ -1462,16 +1463,16 @@ waiting on `async` operations to complete. To resolve this tension, threads are implicitly distinguished by a "keep-alive" flag that determines whether the expectation is that the existence of the thread -is intended to keep the containing component instance alive. In the initial -release of Preview 3, this "keep-alive" flag is default *set* for the [implicit -thread](#summary) created for a task and default *cleared* for the explicit -threads created by `thread.new-indirect`. In particular, this means that an +is intended to keep the containing component instance alive. In [WASI] 0.3, +this "keep-alive" flag is default *set* for the [implicit thread](#summary) +created for a task and default *cleared* for the explicit threads created by +`thread.new-indirect`. In particular, this means that an `async callback`-lifted function will keep its containing component instance alive until it returns the `EXIT` code (`0`). As an example, in JavaScript, the Service Worker API's [`waitUntil`] method -would delay returning the `EXIT` code. In the initial 0.3.0 release without -cooperative threads (🧡), [`setInterval`] would also unfortunately delay +would delay returning the `EXIT` code. In 0.3.0, without cooperative threads +(🧡), [`setInterval`] would also unfortunately delay returning the `EXIT` code and thus, without guest code intervention, would keep component instances alive until timeout limits were hit. The release of cooperative threads would offer a solution to this problem, but an awkward one. @@ -1494,10 +1495,9 @@ the whole tree would be kept alive. ## TODO -Native async support is being proposed incrementally. The following features -will be added in future chunks roughly in the order listed to complete the full -"async" story, with a TBD cutoff between what's in [WASI Preview 3] and what -comes after: +Native async support is being added incrementally. Beyond what's currently +specified, the following features are being considered for addition to complete +the concurrency story: * remove the temporary trap mentioned above that occurs when a `read` and `write` of a stream/future happen from within the same component instance * zero-copy forwarding/splicing @@ -1613,7 +1613,7 @@ comes after: [wasm-gc]: https://github.com/WebAssembly/gc/blob/main/proposals/gc/MVP.md [wasi-libc]: https://github.com/WebAssembly/wasi-libc -[WASI Preview 3]: https://github.com/WebAssembly/WASI/tree/main/wasip2#looking-forward-to-preview-3 +[WASI]: https://github.com/WebAssembly/WASI [Runtime Instantiation]: https://github.com/WebAssembly/component-model/issues/423 [Top-level `await`]: https://github.com/tc39/proposal-top-level-await diff --git a/design/mvp/Explainer.md b/design/mvp/Explainer.md index 20677a5e..19c63425 100644 --- a/design/mvp/Explainer.md +++ b/design/mvp/Explainer.md @@ -39,19 +39,27 @@ more user-focused explanation, take a look at the * [ESM-integration](#ESM-integration) * [Examples](#examples) +(Based on the previous [scoping and layering] proposal to the WebAssembly CG, +this repo merges and supersedes the [module-linking] and [interface-types] +proposals, pushing some of their original features into the post-MVP [future +feature](FutureFeatures.md) backlog.) + + ## Gated Features By default, the features described in this explainer (as well as the supporting [Binary.md](Binary.md), [WIT.md](WIT.md) and [CanonicalABI.md](CanonicalABI.md)) -have been implemented and are included in the [WASI Preview 2] stability -milestone. Features that are not part of Preview 2 are demarcated by one of the -emoji symbols listed below; these emojis will be removed once they are -implemented, considered stable and included in a future milestone: +have been implemented and are included in the [WASI] 0.2 Developer Preview +release. The WASI 0.3 Developer Preview release additionally includes the +features gated by πŸ”€. + +The other features, in various stages of implementation, polish and release, +are gated by the following emojis and, when ready, may be included in +subsequent WASI Developer Preview minor releases: * πŸͺ™: value imports/exports and component-level start function * πŸͺΊ: nested namespaces and packages in import/export names -* πŸ”€: async - * 🚝: enabling more canonical ABI options on more async-related builtins - * 🚟: using `async` with `canon lift` without `callback` (stackful lift) +* 🚝: enabling more canonical ABI options on more async-related builtins +* 🚟: using `async` with `canon lift` without `callback` (stackful lift) * 🧡: threading built-ins * πŸ§΅β‘‘: [shared-everything-threads]-based threading built-ins * πŸ”§: fixed-length lists @@ -61,11 +69,6 @@ implemented, considered stable and included in a future milestone: * πŸ—ΊοΈ: the `map` type * 🏷️: `implements` annotations for plain-named interface imports/exports -(Based on the previous [scoping and layering] proposal to the WebAssembly CG, -this repo merges and supersedes the [module-linking] and [interface-types] -proposals, pushing some of their original features into the post-MVP [future -feature](FutureFeatures.md) backlog.) - ## Grammar @@ -2945,7 +2948,7 @@ have a `canonversion`, and the concatenation of the `canonversion` and For compatibility with older versions of this spec, non-canonical `interfacename`s (with `interfaceversion`s matching any `valid semver`) are temporarily permitted. These non-canonical names may trigger warnings and will -start being rejected some time after after [WASI Preview 3] is released. +be rejected at some point in the future. ## Component Invariants @@ -3319,8 +3322,7 @@ For some use-case-focused, worked examples, see: [memory64]: https://github.com/webAssembly/memory64 [`rectype`]: https://webassembly.github.io/gc/core/text/types.html#text-rectype [shared-everything-threads]: https://github.com/WebAssembly/shared-everything-threads -[WASI Preview 2]: https://github.com/WebAssembly/WASI/tree/main/wasip2#readme -[WASI Preview 3]: https://github.com/WebAssembly/WASI/tree/main/wasip2#looking-forward-to-preview-3 +[WASI]: https://github.com/WebAssembly/WASI [reference types]: https://github.com/WebAssembly/reference-types/blob/master/proposals/reference-types/Overview.md [GC ABI Option]: https://github.com/WebAssembly/component-model/issues/525 diff --git a/design/mvp/Linking.md b/design/mvp/Linking.md index 7616219f..527a3237 100644 --- a/design/mvp/Linking.md +++ b/design/mvp/Linking.md @@ -290,7 +290,7 @@ address this use case *above* the Component Model, using an interface defined in [WIT] and allowing different platforms and applications to tailor the interface to their needs. -For example, using the Preview 2 feature set of Component Model, a simple +For example, using the current feature set of the Component Model, a simple dynamic plugin interface might look like the following: ```wit interface plugin-loader { @@ -314,7 +314,7 @@ plugins (e.g., on upload to the store or registry) into a native shared object or DLL that can be efficiently loaded at runtime. (There are a number of ways to improve upon this basic design with additional -post-Preview 2 features of WIT and the Component Model.) +future features of WIT and the Component Model.) [Canonical ABI]: CanonicalABI.md diff --git a/design/mvp/WIT.md b/design/mvp/WIT.md index 2a4934aa..ba306876 100644 --- a/design/mvp/WIT.md +++ b/design/mvp/WIT.md @@ -1,4 +1,4 @@ -# The `wit` format +# The WIT text format The Wasm Interface Type (WIT) format is an [IDL] to provide tooling for the [WebAssembly Component Model][components] in two primary ways: