diff --git a/design/mvp/Binary.md b/design/mvp/Binary.md index e5c0e1cf..194840c0 100644 --- a/design/mvp/Binary.md +++ b/design/mvp/Binary.md @@ -1,11 +1,10 @@ # Component Model Binary Format Explainer -This document defines the binary format for the AST defined in the -[explainer](Text.md). The top-level production is `component` and the -convention is that a file suffixed in `.wasm` may contain either a -[`core:module`] *or* a `component`, using the `layer` field to discriminate -between the two in the first 8 bytes (see [below](#component-definitions) for -more details). +This document defines the binary format for the AST shared with the [text +format](Text.md). The top-level production is `component` and the convention is +that a file suffixed in `.wasm` may contain either a [`core:module`] *or* a +`component`, using the `layer` field to discriminate between the two in the +first 8 bytes (see [below](#component-definitions) for more details). Note: this document is not meant to completely define the decoding or validation rules, but rather merge the minimal need-to-know elements of both, with just diff --git a/design/mvp/CanonicalABI.md b/design/mvp/CanonicalABI.md index 809c9df5..b949201a 100644 --- a/design/mvp/CanonicalABI.md +++ b/design/mvp/CanonicalABI.md @@ -2,77 +2,11 @@ This document defines the Canonical ABI used to convert between the values and functions of components in the Component Model and the values and functions -of modules in Core WebAssembly. See the [AST explainer](Text.md) for a +of modules in Core WebAssembly. See the [explainer](Explainer.md) for a walkthrough of the static structure of a component and the [concurrency explainer] for a high-level description of the concurrency concepts being specified here. -* [Introduction](#introduction) -* [Component Instances](#component-instances) -* [Concurrency](#concurrency) - * [Stack Switching](#stack-switching) - * [Threads](#threads) - * [Tasks](#tasks) -* [Embedding](#embedding) -* [Canonical ABI Options](#canonical-abi-options) -* [Lifting and Lowering Context](#lifting-and-lowering-context) -* [Runtime State](#runtime-state) - * [Table State](#table-state) - * [Resource State](#resource-state) - * [Waitable State](#waitable-state) - * [Subtask State](#subtask-state) - * [Buffer State](#buffer-state) - * [Stream and Future State](#stream-and-future-state) -* [Despecialization](#despecialization) -* [Type Predicates](#type-predicates) -* [Alignment](#alignment) -* [Element Size](#element-size) -* [Loading](#loading) -* [Storing](#storing) -* [Flattening](#flattening) -* [Flat Lifting](#flat-lifting) -* [Flat Lowering](#flat-lowering) -* [Lifting and Lowering Values](#lifting-and-lowering-values) -* [Canonical definitions](#canonical-definitions) - * [`canonopt` Validation](#canonopt-validation) - * [`canon lift`](#canon-lift) - * [`canon lower`](#canon-lower) - * [`canon resource.new`](#canon-resourcenew) - * [`canon resource.drop`](#canon-resourcedrop) - * [`canon resource.rep`](#canon-resourcerep) - * [`canon context.get`](#-canon-contextget) ๐Ÿ”€ - * [`canon context.set`](#-canon-contextset) ๐Ÿ”€ - * [`canon backpressure.{inc,dec}`](#-canon-backpressureincdec) ๐Ÿ”€ - * [`canon task.return`](#-canon-taskreturn) ๐Ÿ”€ - * [`canon task.cancel`](#-canon-taskcancel) ๐Ÿ”€ - * [`canon waitable-set.new`](#-canon-waitable-setnew) ๐Ÿ”€ - * [`canon waitable-set.wait`](#-canon-waitable-setwait) ๐Ÿ”€ - * [`canon waitable-set.poll`](#-canon-waitable-setpoll) ๐Ÿ”€ - * [`canon waitable-set.drop`](#-canon-waitable-setdrop) ๐Ÿ”€ - * [`canon waitable.join`](#-canon-waitablejoin) ๐Ÿ”€ - * [`canon subtask.cancel`](#-canon-subtaskcancel) ๐Ÿ”€ - * [`canon subtask.drop`](#-canon-subtaskdrop) ๐Ÿ”€ - * [`canon {stream,future}.new`](#-canon-streamfuturenew) ๐Ÿ”€ - * [`canon {stream,future}.{read,write}`](#-canon-streamfuturereadwrite) ๐Ÿ”€ - * [`canon {stream,future}.cancel-{read,write}`](#-canon-streamfuturecancel-readwrite) ๐Ÿ”€ - * [`canon {stream,future}.drop-{readable,writable}`](#-canon-streamfuturedrop-readablewritable) ๐Ÿ”€ - * [`canon {stream,future}.forward`](#-canon-streamfutureforward) โžก๏ธ - * [`canon thread.index`](#-canon-threadindex) ๐Ÿงต - * [`canon thread.new-indirect`](#-canon-threadnew-indirect) ๐Ÿงต - * [`canon thread.resume-later`](#-canon-threadresume-later) ๐Ÿงต - * [`canon thread.suspend`](#-canon-threadsuspend) ๐Ÿงต - * [`canon thread.yield`](#-canon-threadyield) ๐Ÿ”€ - * [`canon thread.suspend-then-resume`](#-canon-threadsuspend-then-resume) ๐Ÿงต - * [`canon thread.yield-then-resume`](#-canon-threadyield-then-resume) ๐Ÿงต - * [`canon thread.suspend-then-promote`](#-canon-threadsuspend-then-promote) ๐Ÿงต - * [`canon thread.yield-then-promote`](#-canon-threadyield-then-promote) ๐Ÿงต - * [`canon error-context.new`](#-canon-error-contextnew) ๐Ÿ“ - * [`canon error-context.debug-message`](#-canon-error-contextdebug-message) ๐Ÿ“ - * [`canon error-context.drop`](#-canon-error-contextdrop) ๐Ÿ“ - * [`canon thread.spawn-ref`](#-canon-threadspawn-ref) ๐Ÿงตโ‘ก - * [`canon thread.spawn-indirect`](#-canon-threadspawn-indirect) ๐Ÿงตโ‘ก - * [`canon thread.available-parallelism`](#-canon-threadavailable-parallelism) ๐Ÿงตโ‘ก - ## Introduction diff --git a/design/mvp/Concurrency.md b/design/mvp/Concurrency.md index 79d8a1ac..f9762aee 100644 --- a/design/mvp/Concurrency.md +++ b/design/mvp/Concurrency.md @@ -1,37 +1,10 @@ # Concurrency Explainer -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 +This document contains a high-level summary of the Component Model's concurrency +support, providing background for understanding the definitions in the [WIT], +[text format], [binary format] and [Canonical ABI explainer] documents that are gated by the ๐Ÿ”€ (async) and ๐Ÿงต (threading) emojis. -* [Goals](#goals) -* [Summary](#summary) -* [Concepts](#concepts) - * [Threads and Tasks](#threads-and-tasks) - * [Subtasks and Supertasks](#subtasks-and-supertasks) - * [Current Thread and Task](#current-thread-and-task) - * [Thread Built-ins](#thread-built-ins) - * [Thread-Local Storage](#thread-local-storage) - * [Blocking](#blocking) - * [Waitables and Waitable Sets](#waitables-and-waitable-sets) - * [Streams and Futures](#streams-and-futures) - * [Stream Readiness](#stream-readiness) - * [Backpressure](#backpressure) - * [Returning](#returning) - * [Borrows](#borrows) - * [Cancellation](#cancellation) - * [Nondeterminism](#nondeterminism) - * [Reentrance](#reentrance) -* [Interaction with the start function](#interaction-with-the-start-function) -* [Async ABI](#async-abi) - * [Async Import ABI](#async-import-abi) - * [Async Export ABI](#async-export-abi) -* [Examples](#examples) -* [Component Instance Lifetime](#component-instance-lifetime) -* [Guest Language Task Affinity](#guest-language-task-affinity) -* [TODO](#todo) - ## Goals @@ -493,7 +466,7 @@ Thus, if any *non*-entry-trampoline code calls `context.set`, it is the responsibility of *that code* to restore this default assumption before allowing control flow to escape into the wild. -For more information, see [`context.get`] in the AST explainer. +For more information, see [`context.get`]. ### Blocking @@ -1590,7 +1563,7 @@ the concurrency story: [`waitUntil`]: https://developer.mozilla.org/en-US/docs/Web/API/ExtendableEvent/waitUntil [`setInterval`]: https://developer.mozilla.org/en-US/docs/Web/API/Window/setInterval -[AST Explainer]: Text.md +[Text Format]: Text.md [Canonical Built-in]: Text.md#canonical-built-ins [Component Invariant]: Text.md#component-invariants [`context.get`]: Text.md#-contextget diff --git a/design/mvp/Text.md b/design/mvp/Text.md index 82cc0d03..2b785cf2 100644 --- a/design/mvp/Text.md +++ b/design/mvp/Text.md @@ -1,47 +1,7 @@ # Text Format / AST Explainer -This explainer walks through the grammar of a [component](../high-level) and -the proposed embedding of components into native JavaScript runtimes. For a -more user-focused explanation, take a look at the -**[Component Model Documentation]**. - -* [Gated features](#gated-features) -* [Grammar](#grammar) - * [Index spaces](#index-spaces) - * [Component definitions](#component-definitions) - * [Instance definitions](#instance-definitions) - * [Alias definitions](#alias-definitions) - * [Type definitions](#type-definitions) - * [Fundamental value types](#fundamental-value-types) - * [Numeric types](#numeric-types) - * [Error Context type](#-error-context-type) - * [Container types](#container-types) - * [Handle types](#handle-types) - * [Asynchronous value types](#asynchronous-value-types) - * [Specialized value types](#specialized-value-types) - * [Definition types](#definition-types) - * [Declarators](#declarators) - * [Type checking](#type-checking) - * [Canonical definitions](#canonical-definitions) - * [Canonical ABI](#canonical-abi) - * [Canonical built-ins](#canonical-built-ins) - * [Resource built-ins](#resource-built-ins) - * [Concurrency built-ins](#-concurrency-built-ins) - * [Error Context built-ins](#-error-context-built-ins) - * [Value definitions](#-value-definitions) - * [Start definitions](#-start-definitions) - * [Import and export definitions](#import-and-export-definitions) - * [Name uniqueness](#name-uniqueness) - * [Canonical interface name](#-canonical-interface-name) - * [External visibility of types](#external-visibility-of-types) -* [Component invariants](#component-invariants) -* [JavaScript embedding](#JavaScript-embedding) -* [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.) +This explainer walks through the text format of the Component Model which +extends the Core WebAssembly text format (WAT). ## Gated Features @@ -3206,7 +3166,6 @@ For some use-case-focused, worked examples, see: [Non-Parametric Parametricity]: https://people.mpi-sws.org/~dreyer/papers/npp/main.pdf [module-linking]: https://github.com/WebAssembly/module-linking/blob/main/proposals/module-linking/Explainer.md -[interface-types]: https://github.com/WebAssembly/interface-types/blob/main/proposals/interface-types/Explainer.md [type-imports]: https://github.com/WebAssembly/proposal-type-imports/blob/master/proposals/type-imports/Overview.md [exception-handling]: https://github.com/WebAssembly/exception-handling/blob/main/proposals/exception-handling/Exceptions.md [stack-switching]: https://github.com/WebAssembly/stack-switching/blob/main/proposals/stack-switching/Explainer.md @@ -3281,8 +3240,4 @@ For some use-case-focused, worked examples, see: [Resolved]: Concurrency.md#cancellation [Cancellation]: Concurrency.md#cancellation -[Component Model Documentation]: https://component-model.bytecodealliance.org - -[Scoping and Layering]: https://docs.google.com/presentation/d/1PSC3Q5oFsJEaYyV5lNJvVgh-SNxhySWUqZ6puyojMi8 - [`navigator.hardwareConcurrency`]: https://developer.mozilla.org/en-US/docs/Web/API/Navigator/hardwareConcurrency