Merge remote-tracking branch 'origin/main' into clarify-options

Author: alexcrichton

design/mvp/Async.md

@@ -16,12 +16,12 @@ summary of the motivation and animated sketch of the design in action.
   * [Task](#task)
   * [Current task](#current-task)
   * [Context-Local Storage](#context-local-storage)
-  * [Subtask and Supertask](#subtask-and-supertask)
   * [Structured concurrency](#structured-concurrency)
   * [Streams and Futures](#streams-and-futures)
   * [Waiting](#waiting)
   * [Backpressure](#backpressure)
   * [Returning](#returning)
+  * [Borrows](#borrows)
 * [Async ABI](#async-abi)
   * [Async Import ABI](#async-import-abi)
   * [Async Export ABI](#async-export-abi)
@@ -251,70 +251,64 @@ reason why "context-local" storage is not called "task-local" storage (where a
 For details, see [`context.get`] in the AST explainer and [`canon_context_get`]
 in the Canonical ABI explainer.
 
-### Subtask and Supertask
-
-Each component-to-component call necessarily creates a new task in the callee.
-The callee task is a **subtask** of the calling task (and, conversely, the
-calling task is a **supertask** of the callee task. This sub/super relationship
-is immutable and doesn't change over time (until the callee task completes and
-is destroyed).
-
-The Canonical ABI's Python code represents the subtask relationship between a
-caller `Task` and a callee `Task` via the Python [`Subtask`] class. Whereas a
-`Task` object is created by each call to [`canon_lift`], a `Subtask` object is
-created by each call to [`canon_lower`]. This allows `Subtask`s to store the
-state that enforces the caller side of the Canonical ABI rules.
-
 ### Structured concurrency
 
-To realize the above goals of always having a well-defined cross-component
-async callstack, the Component Model's Canonical ABI enforces [Structured
-Concurrency] by dynamically requiring that a task waits for all its subtasks to
-[return](#returning) before the task itself is allowed to finish. This means
-that a subtask cannot be orphaned and there will always be an async callstack
-rooted at an invocation of an export by the host. Moreover, at any one point in
-time, the set of tasks active in a linked component graph form a forest of
-async call trees which e.g., can be visualized using a traditional flamegraph.
-
-The Canonical ABI's Python code enforces Structured Concurrency by incrementing
-a per-task "`num_subtasks`" counter when a subtask is created, decrementing
-when the subtask [returns](#returning), and trapping if `num_subtasks > 0` when
-a task attempts to exit.
-
-There is a subtle nuance to these Structured Concurrency rules deriving from
-the fact that subtasks may continue execution after [returning](#returning)
-their value to their caller. The ability to execute after returning value is
-necessary for being able to do work off the caller's critical path. A concrete
-example is an HTTP service that does some logging or billing operations after
-finishing an HTTP response, where the HTTP response is the return value of the
-[`wasi:http/handler.handle`] function. Since the `num_subtasks` counter is
-decremented when a subtask *returns* (as opposed to *exits*), this means that
-subtasks may continue execution even once their supertask has exited. To
-maintain Structured Concurrency (for purposes of checking [reentrance],
-scheduler prioritization and debugging/observability), we can consider
-the supertask to still be alive but in the process of "asynchronously
-tail-calling" its still-executing subtasks. (For scenarios where one
-component wants to non-cooperatively bound the execution of another
-component, a separate "[blast zone]" feature is necessary in any
-case.)
-
-This async call tree provided by Structured Concurrency interacts naturally
-with the `borrow` handle type and its associated dynamic rules for preventing
-use-after-free. When a caller initially lends an `own`ed or `borrow`ed handle
-to a callee, a "`num_lends`" counter on the lent handle is incremented when the
-subtask starts and decremented when the caller is notified that the subtask has
-[returned](#returning). If the caller tries to drop a handle while the handle's
-`num_lends` is greater than zero, it traps. Symmetrically, each `borrow` handle
-passed to a callee task increments a "`num_borrows`" counter on the task that
-is decremented when the `borrow` handle is dropped. With async calls, there can
-of course be multiple overlapping async tasks and thus `borrow` handles must
-remember which particular task's `num_borrows` counter to drop. If a task
-attempts to return (which, for `async` tasks, means calling `task.return`) when
-its `num_borrows` is greater than zero, it traps. These interlocking rules for
-the `num_lends` and `num_borrows` fields inductively ensure that nested async
-call trees that transitively propagate `borrow`ed handles maintain the
-essential invariant that dropping an `own`ed handle never destroys a resource
-while there is any `borrow` handle anywhere pointing to that resource.
+Calling *into* a component creates a `Task` to track ABI state related to the
+*callee* (like "number of outstanding borrows"). Calling *out* of a component
+creates a `Subtask` to track ABI state related to the *caller* (like "which
+handles have been lent"). When one component calls another, there is thus a
+`Subtask`+`Task` pair that collectively maintains the overall state of the call
+and enforces that both components uphold their end of the ABI contract. But
+when the host calls into a component, there is only a `Task` and,
+symmetrically, when a component calls into the host, there is only a `Subtask`.
+
+Based on this, the call stack at any point in time when a component calls a
+host-defined import will have a callstack of the general form:
+```
+[Host caller] <- [Task] <- [Subtask+Task]* <- [Subtask] <- [Host callee]
+```
+Here, the `<-` arrow represents the `supertask` relationship that is immutably
+established when first making the call. A paired `Subtask` and `Task` have the
+same `supertask` and can thus be visualized as a single node in the callstack.
+
+(These concepts are represented in the Canonical ABI Python code via the
+[`Task`] and [`Subtask`] classes.)
+
+One semantically-observable use of this async call stack is to distinguish
+between hazardous **recursive reentrance**, in which a component instance is
+reentered when one of its tasks is already on the callstack, from
+business-as-usual **sibling reentrance**, in which a component instance is
+freshly reentered when its other tasks are suspended waiting on I/O. Recursive
+reentrance currently always traps, but may be allowed (and indicated to core
+wasm) in an opt-in manner in the [future](#TODO).
+
+The async call stack is also useful for non-semantic purposes such as providing
+backtraces when debugging, profiling and distributed tracing. While particular
+languages can and do maintain their own async call stacks in core wasm state,
+without the Component Model's async call stack, linkage *between* different
+languages would be lost at component boundaries, leading to a loss of overall
+context in multi-component applications.
+
+There is an important nuance to the Component Model's minimal form of
+Structured Concurrency compared to Structured Concurrency support that appears
+in popular source language features/libraries. Often, "Structured Concurrency"
+refers to an invariant that all "child" tasks finish or are cancelled before a
+"parent" task completes. However, the Component Model doesn't force subtasks to
+[return](#returning) or be cancelled before the supertask returns (this is left
+as an option to particular source langauges to enforce or not). The reason for
+not enforcing a stricter form of Structured Concurrency at the Component
+Model level is that there are important use cases where forcing a supertask to
+stay resident simply to wait for a subtask to finish would waste resources
+without tangible benefit. Instead, we can say that once the core wasm
+implementing a supertask finishes execution, the supertask semantically "tail
+calls" any still-live subtasks, staying technically-alive until they complete,
+but not consuming real resources. Concretely, this means that a supertask that
+finishes executing stays on the callstack of any still-executing subtasks for
+the abovementioned purposes until all transitive subtasks finish.
+
+For scenarios where one component wants to *non-cooperatively* put an upper
+bound on execution of a call into another component, a separate "[blast zone]"
+feature is necessary in any case (due to iloops and traps).
 
 ### Streams and Futures
 
@@ -486,6 +480,28 @@ A task may not call `task.return` unless it is in the "started" state. Once
 finish once it is in the "returned" state. See the [`canon_task_return`]
 function in the Canonical ABI explainer for more details.
 
+### Borrows
+
+Component Model async support is careful to ensure that `borrow`ed handles work
+as expected in an asynchronous setting, extending the dynamic enforcement used
+for synchronous code:
+
+When a caller initially lends an `own`ed or `borrow`ed handle to a callee, a
+`num_lends` counter on the lent handle is incremented when the subtask starts
+and decremented when the caller is notified that the subtask has
+[returned](#returning). If the caller tries to drop a handle while the handle's
+`num_lends` is greater than zero, the caller traps. Symmetrically, each
+`borrow` handle passed to a callee increments a `num_borrows` counter on the
+callee task that is decremented when the `borrow` handle is dropped. If a
+callee task attempts to return when its `num_borrows` is greater than zero, the
+callee traps.
+
+In an asynchronous setting, the only generalization necessary is that, since
+there can be multiple overlapping async tasks executing in a component
+instance, a borrowed handle must track *which* task's `num_borrow`s was
+incremented so that the correct counter can be decremented.
+
+
 ## Async ABI
 
 At an ABI level, native async in the Component Model defines for every WIT
@@ -962,6 +978,7 @@ comes after:
 [`Task.enter`]: CanonicalABI.md#task-state
 [`Task.wait`]: CanonicalABI.md#task-state
 [`Waitable`]: CanonicalABI.md#waitable-state
+[`Task`]: CanonicalABI.md#task-state
 [`Subtask`]: CanonicalABI.md#subtask-state
 [Stream State]: CanonicalABI.md#stream-state
 [Future State]: CanonicalABI.md#future-state

design/mvp/CanonicalABI.md

@@ -129,35 +129,36 @@ known to not contain `borrow`. The `CanonicalOptions`, `ComponentInstance`,
 
 ### Canonical ABI Options
 
-The following two classes list the various Canonical ABI options ([`canonopt`])
-that can be set on various Canonical ABI definitions. The default values of the
-Python fields are the default values when the associated `canonopt` is not
-present in the binary or text format definition.
+The following classes list the various Canonical ABI options ([`canonopt`])
+that can be set on various Canonical ABI definitions. The default values of
+the Python fields are the default values when the associated `canonopt` is
+not present in the binary or text format definition.
 
-The `LiftLowerContext` class contains the subset of [`canonopt`] which are
-used to lift and lower the individual parameters and results of function
-calls:
+The `LiftOptions` class contains the subset of [`canonopt`] which are needed
+when lifting individual parameters and results:
 ```python
 @dataclass
-class LiftLowerOptions:
+class LiftOptions:
   string_encoding: str = 'utf8'
   memory: Optional[bytearray] = None
-  realloc: Optional[Callable] = None
 
-  def __eq__(self, other):
-    return self.string_encoding == other.string_encoding and \
-           self.memory is other.memory and \
-           self.realloc is other.realloc
+  def equal(lhs, rhs):
+    return lhs.string_encoding == rhs.string_encoding and \
+           lhs.memory is rhs.memory
+```
+The `equal` static method is used by `task.return` below to dynamically
+compare equality of just this subset of `canonopt`.
 
-  def copy(opts):
-    return LiftLowerOptions(opts.string_encoding, opts.memory, opts.realloc)
+The `LiftLowerOptions` class contains the subset of [`canonopt`] which are
+needed when lifting *or* lowering individual parameters and results:
+```python
+@dataclass
+class LiftLowerOptions(LiftOptions):
+  realloc: Optional[Callable] = None
 ```
-The `__eq__` override specifies that equality of `LiftLowerOptions` (as used
-by, e.g., `canon_task_return` below) is defined in terms of the identity of
-the memory and `realloc`-function instances.
 
-The `CanonicalOptions` class contains the rest of the [`canonopt`] options
-that affect how an overall function is lifted/lowered:
+The `CanonicalOptions` class contains the rest of the [`canonopt`]
+options that affect how an overall function is lifted/lowered:
 ```python
 @dataclass
 class CanonicalOptions(LiftLowerOptions):
@@ -470,21 +471,19 @@ class Task:
   opts: CanonicalOptions
   inst: ComponentInstance
   ft: FuncType
-  caller: Optional[Task]
+  supertask: Optional[Task]
   on_return: Optional[Callable]
   on_block: Callable[[Awaitable], Awaitable]
-  num_subtasks: int
   num_borrows: int
   context: ContextLocalStorage
 
-  def __init__(self, opts, inst, ft, caller, on_return, on_block):
+  def __init__(self, opts, inst, ft, supertask, on_return, on_block):
     self.opts = opts
     self.inst = inst
     self.ft = ft
-    self.caller = caller
+    self.supertask = supertask
     self.on_return = on_return
     self.on_block = on_block
-    self.num_subtasks = 0
     self.num_borrows = 0
     self.context = ContextLocalStorage()
 ```
@@ -559,7 +558,7 @@ the given arguments into the callee's memory (possibly executing `realloc`)
 returning the final set of flat arguments to pass into the core wasm callee.
 
 The `Task.trap_if_on_the_stack` method called by `enter` prevents reentrance
-using the `caller` field of `Task` which points to the task's supertask in the
+using the `supertask` field of `Task` which points to the task's supertask in the
 async call tree defined by [structured concurrency]. Structured concurrency
 is necessary to distinguish between the deadlock-hazardous kind of reentrance
 (where the new task is a transitive subtask of a task already running in the
@@ -570,10 +569,10 @@ function to opt in (via function type attribute) to the hazardous kind of
 reentrance, which will nuance this test.
 ```python
   def trap_if_on_the_stack(self, inst):
-    c = self.caller
+    c = self.supertask
     while c is not None:
       trap_if(c.inst is inst)
-      c = c.caller
+      c = c.supertask
 ```
 An optimizing implementation can avoid the O(n) loop in `trap_if_on_the_stack`
 in several ways:
@@ -792,7 +791,6 @@ may be a synchronous task unblocked by the clearing of `calling_sync_export`.
 ```python
   def exit(self):
     assert(Task.current.locked())
-    trap_if(self.num_subtasks > 0)
     trap_if(self.on_return)
     assert(self.num_borrows == 0)
     if self.opts.sync:
@@ -806,7 +804,7 @@ may be a synchronous task unblocked by the clearing of `calling_sync_export`.
 
 A "waitable" is anything that can be stored in the component instance's
 `waitables` table. Currently, there are 5 different kinds of waitables:
-[subtasks](Async.md#subtask-and-supertask) and the 4 combinations of the
+[subtasks](Async.md#structured-concurrency) and the 4 combinations of the
 [readable and writable ends of futures and streams](Async.md#streams-and-futures).
 
 Waitables deliver "events" which are values of the following `EventTuple` type.
@@ -964,18 +962,10 @@ delivery.
 #### Subtask State
 
 While `canon_lift` creates `Task` objects when called, `canon_lower` creates
-`Subtask` objects when called. If the callee (being `canon_lower`ed) is another
-component's (`canon_lift`ed) function, there will thus be a `Subtask`+`Task`
-pair created. However, if the callee is a host-defined function, the `Subtask`
-will stand alone. Thus, in general, the call stack at any point in time when
-wasm calls a host-defined import will have the form:
-```
-[Host caller] -> [Task] -> [Subtask+Task]* -> [Subtask] -> [Host callee]
-```
-
-The `Subtask` class is simpler than `Task` and only manages a few fields of
-state that are relevant to the caller. As with `Task`, this section will
-introduce `Subtask` incrementally, starting with its fields and initialization:
+`Subtask` objects when called. The `Subtask` class is simpler than `Task` and
+only manages a few fields of state that are relevant to the caller. As with
+`Task`, this section will introduce `Subtask` incrementally, starting with its
+fields and initialization:
 ```python
 class Subtask(Waitable):
   state: CallState
@@ -1003,14 +993,9 @@ turn only happens if the call is `async` *and* blocks. In this case, the
   def add_to_waitables(self, task):
     assert(not self.supertask)
     self.supertask = task
-    self.supertask.num_subtasks += 1
     Waitable.__init__(self)
     return task.inst.waitables.add(self)
 ```
-The `num_subtasks` increment ensures that the parent `Task` cannot `exit`
-without having waited for all its subtasks to return (or, in the
-[future](Async.md#TODO) be cancelled), thereby preserving [structured
-concurrency].
 
 The `Subtask.add_lender` method is called by `lift_borrow` (below). This method
 increments the `num_lends` counter on the handle being lifted, which is guarded
@@ -1041,7 +1026,6 @@ its value to the caller.
   def drop(self):
     trap_if(not self.finished)
     assert(self.state == CallState.RETURNED)
-    self.supertask.num_subtasks -= 1
     Waitable.drop(self)
 ```
 
@@ -3257,7 +3241,7 @@ async def canon_task_return(task, result_type, opts: LiftLowerOptions, flat_args
   trap_if(not task.inst.may_leave)
   trap_if(task.opts.sync and not task.opts.always_task_return)
   trap_if(result_type != task.ft.results)
-  trap_if(opts != LiftLowerOptions.copy(task.opts))
+  trap_if(not LiftOptions.equal(opts, task.opts))
   task.return_(flat_args)
   return []
 ```
@@ -3266,13 +3250,18 @@ component with multiple exported functions of different types, `task.return` is
 not called with a mismatched result type (which, due to indirect control flow,
 can in general only be caught dynamically).
 
-The `trap_if(opts != LiftLowerOptions.copy(task.opts))` guard ensures that
-the return value is lifted the same way as the `canon lift` from which this
+The `trap_if(not LiftOptions.equal(opts, task.opts))` guard ensures that the
+return value is lifted the same way as the `canon lift` from which this
 `task.return` is returning. This ensures that AOT fusion of `canon lift` and
 `canon lower` can generate a thunk that is indirectly called by `task.return`
-after these guards. The `LiftLowerOptions.copy` method is used to select just
-the `LiftLowerOptions` subset of `CanonicalOptions` (since fields like
-`async` and `callback` aren't relevant to `task.return`).
+after these guards. Inside `LiftOptions.equal`, `opts.memory` is compared with
+`task.opts.memory` via object identity of the mutable memory instance. Since
+`memory` refers to a mutable *instance* of memory, this comparison is not
+concerned with the static memory indices (in `canon lift` and `canon
+task.return`), only the identity of the memories created
+at instantiation-/ run-time. In Core WebAssembly spec terms, the test is on the
+equality of the [`memaddr`] values stored in the instance's [`memaddrs` table]
+which is indexed by the static [`memidx`].
 
 
 ### 🔀 `canon yield`
@@ -3972,6 +3961,9 @@ def canon_thread_available_parallelism():
 [WASI]: https://github.com/webassembly/wasi
 [Deterministic Profile]: https://github.com/WebAssembly/profiles/blob/main/proposals/profiles/Overview.md
 [stack-switching]: https://github.com/WebAssembly/stack-switching
+[`memaddr`]: https://webassembly.github.io/spec/core/exec/runtime.html#syntax-memaddr
+[`memaddrs` table]: https://webassembly.github.io/spec/core/exec/runtime.html#syntax-moduleinst
+[`memidx`]: https://webassembly.github.io/spec/core/syntax/modules.html#syntax-memidx
 
 [Alignment]: https://en.wikipedia.org/wiki/Data_structure_alignment
 [UTF-8]: https://en.wikipedia.org/wiki/UTF-8