Remove always-task-return, clear may_leave during post-return, expand Async.md (#531)

Author: lukewagner

design/mvp/Async.md

@@ -67,12 +67,10 @@ by allowing components to import and export "async" functions which abstract
 over, and can be implemented by, idiomatic concurrency in a variety of
 programming languages:
 * `async` functions in languages like C#, JS, Python, Rust and Swift
-  (implemented using [`callback` functions](#waiting))
 * stackful coroutines in languages like Kotlin, Perl, PHP and (recently) C++
 * green threads as-if running on a single OS thread in languages like Go and
   (initially and recently again) Java
 * callbacks, in languages with no explicit async support
-  (also implemented using [`callback` functions](#waiting))
 
 The Component Model supports this wide variety of language features by
 specifying a common low-level "async" ABI which the different languages'
@@ -84,10 +82,9 @@ Model "just another OS" from the language toolchains' perspective).
 
 Moreover, this async ABI does not require components to use preemptive
 multi-threading ([`thread.spawn*`]) in order to achieve concurrency. Instead,
-concurrency can be achieved by cooperatively switching between different logical
-tasks running on a single thread. This switching may require the use of [fibers]
-or a [CPS transform], but may also be avoided entirely when a component's
-producer toolchain is engineered to always return to an [event loop].
+concurrency can be achieved by cooperatively switching between different
+logical tasks running on a single thread using [fibers] or a [CPS transform] in
+the wasm runtime as necessary.
 
 To avoid partitioning the world along sync/async lines as mentioned in the
 Goals section, the Component Model allows *every* component-level function type
@@ -98,6 +95,22 @@ well-defined behavior. Specifically, the caller and callee can independently
 specify `async` as an immediate flags on the [lift and lower definitions] used
 to define their imports and exports.
 
+To provide wasm runtimes with additional optimization opportunities for
+languages with "stackless" concurrency (e.g. languages using `async`/`await`),
+two `async` ABI sub-options are provided: a "stackless" ABI selected by
+providing a `callback` function and a "stackful" ABI selected by *not*
+providing a `callback` function. The stackless ABI allows core wasm to
+repeatedly return to an [event loop] to receive events concerning a selected
+set of "waitables", thereby clearing the native stack when waiting for events
+and allowing the runtime to reuse stack segments between events. In the
+[future](#TODO), a `strict-callback` option may be added to require (via
+runtime traps) *all* waiting to happen via the event loop, thereby giving the
+engine more up-front information that the engine can use to avoid allocating
+[fibers] in more cases. In the meantime, to support complex applications with
+mixed dependencies and concurrency models, the `callback` immediate allows
+*both* returning to the event loop *and* making blocking calls to wait for
+event.
+
 To propagate backpressure, it's necessary for a component to be able to say
 "there are too many async export calls already in progress, don't start any
 more until I let some of them complete". Thus, the low-level async ABI provides
@@ -280,7 +293,7 @@ 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 when a component calls a host-defined import will 
+Based on this, the call stack when a component calls a host-defined import will
 have the general form:
 ```
 [Host]
@@ -421,12 +434,11 @@ The Canonical ABI provides two ways for a task to wait on a waitable set:
   the waitable set as a return value to the event loop, which will block and
   then pass the event that occurred as a parameter to the `callback`.
 
-While the two approaches have significant runtime implementation differences
-(the former requires [fibers] or a [CPS transform] while the latter only
-requires storing fixed-size context-local storage and [`Task`] state),
+While the two approaches have significant runtime implementation differences,
 semantically they do the same thing which, in the Canonical ABI Python code, is
-factored out into the [`Task.wait_on`] method. Thus, the difference between
-`callback` and non-`callback` is one of optimization, not expressivity.
+factored out into the [`Task.wait_for_event`] method. Thus, the difference between
+`callback` and non-`callback` is one of optimization (as described
+[above](#high-level-approach)), not expressivity.
 
 In addition to waiting for an event to occur, a task can also **poll** for
 whether an event has already occurred. Polling does not block, but does allow
@@ -469,10 +481,7 @@ the "started" state.
 ### Returning
 
 The way an async function returns its value is by calling [`task.return`],
-passing the core values that are to be lifted as *parameters*. Additionally,
-when the `always-task-return` `canonopt` is set, synchronous functions also
-return their values by calling `task.return` (as a more expressive and
-general alternative to `post-return`).
+passing the core values that are to be lifted as *parameters*.
 
 Returning values by calling `task.return` allows a task to continue executing
 even after it has passed its initial results to the caller. This can be useful
@@ -1090,6 +1099,9 @@ comes after:
 * `recursive` function type attribute: allow a function to opt in to
   recursive [reentrance], extending the ABI to link the inner and
   outer activations
+* add a `strict-callback` option that adds extra trapping conditions to
+  provide the semantic guarantees needed for engines to statically avoid
+  fiber creation at component-to-component `async` call boundaries
 * add `stringstream` specialization of `stream<char>` (just like `string` is
   a specialization of `list<char>`)
 * allow pipelining multiple `stream.read`/`write` calls
@@ -1140,7 +1152,7 @@ comes after:
 [`canon_subtask_cancel`]: CanonicalABI.md#-canon-subtaskcancel
 [`Task`]: CanonicalABI.md#task-state
 [`Task.enter`]: CanonicalABI.md#task-state
-[`Task.wait_on`]: CanonicalABI.md#task-state
+[`Task.wait_for_event`]: CanonicalABI.md#task-state
 [`Waitable`]: CanonicalABI.md#waitable-state
 [`TASK_CANCELLED`]: CanonicalABI.md#waitable-state
 [`Task`]: CanonicalABI.md#task-state

design/mvp/Binary.md

@@ -333,7 +333,6 @@ canonopt ::= 0x00                                                => string-encod
            | 0x05 f:<core:funcidx>                               => (post-return f)
            | 0x06                                                => async 🔀
            | 0x07 f:<core:funcidx>                               => (callback f) 🔀
-           | 0x08                                                => always-task-return 🔀
 ```
 Notes:
 * The second `0x00` byte in `canon` stands for the `func` sort and thus the

design/mvp/CanonicalABI.md

@@ -166,7 +166,6 @@ class CanonicalOptions(LiftLowerOptions):
   post_return: Optional[Callable] = None
   sync: bool = True # = !canonopt.async
   callback: Optional[Callable] = None
-  always_task_return: bool = False
 ```
 (Note that the `async` `canonopt` is inverted to `sync` here for the practical
 reason that `async` is a keyword and most branches below want to start with the
@@ -3003,27 +3002,30 @@ Each call to `canon lift` creates a new `Task` and waits to enter the component
 instance, allowing the component instance to express backpressure before
 lowering the arguments into the callee's memory.
 
-In the synchronous case, if `always-task-return` ABI option is set, the lifted
-core wasm code must call `canon_task_return` to return a value before returning
-to `canon_lift` (or else there will be a trap in `Task.exit`), which allows the
-core wasm to do cleanup and finalization before returning. Otherwise, if
-`always-task-return` is *not* set, `canon_lift` will implicitly call
-`canon_task_return` when core wasm returns and then make a second call into the
-`post-return` function to let core wasm do cleanup and finalization. In the
-future, `post-return` and the option to not set `always-task-return` may be
-deprecated and removed.
+In the synchronous case, `canon_lift` first calls into the lifted core
+function, passing the lowered core flat parameters and receiving the core flat
+results to be lifted. Once the core results are lifted, `canon_lift` optionally
+makes a second call into any supplied `post-return` function, passing the flat
+results as arguments so that the guest code and free any allocations associated
+with compound return values.
 ```python
   if opts.sync:
     flat_results = await call_and_trap_on_throw(callee, task, flat_args)
-    if not opts.always_task_return:
-      assert(types_match_values(flat_ft.results, flat_results))
-      results = lift_flat_values(cx, MAX_FLAT_RESULTS, CoreValueIter(flat_results), ft.result_types())
-      task.return_(results)
-      if opts.post_return is not None:
-        [] = await call_and_trap_on_throw(opts.post_return, task, flat_results)
+    assert(types_match_values(flat_ft.results, flat_results))
+    results = lift_flat_values(cx, MAX_FLAT_RESULTS, CoreValueIter(flat_results), ft.result_types())
+    task.return_(results)
+    if opts.post_return is not None:
+      task.inst.may_leave = False
+      [] = await call_and_trap_on_throw(opts.post_return, task, flat_results)
+      task.inst.may_leave = True
     task.exit()
     return
 ```
+By clearing `may_leave` for the duration of the `post-return` call, the
+Canonical ABI ensures that synchronously-lowered calls to synchronously-lifted
+functions can always be implemented by a plain synchronous function call
+without the need for fibers which would otherwise be necessary if the
+`post-return` function performed a blocking operation.
 
 In both of the asynchronous cases below (`callback` and non-`callback`),
 `canon_task_return` must be called (as checked by `Task.exit`).
@@ -3386,14 +3388,18 @@ wasm state and passes them to the caller via `Task.return_`:
 ```python
 async def canon_task_return(task, result_type, opts: LiftOptions, flat_args):
   trap_if(not task.inst.may_leave)
-  trap_if(task.opts.sync and not task.opts.always_task_return)
+  trap_if(task.opts.sync)
   trap_if(result_type != task.ft.results)
   trap_if(not LiftOptions.equal(opts, task.opts))
   cx = LiftLowerContext(opts, task.inst, task)
   results = lift_flat_values(cx, MAX_FLAT_PARAMS, CoreValueIter(flat_args), task.ft.result_types())
   task.return_(results)
   return []
 ```
+The `trap_if(task.opts.sync)` prevents `task.return` from being called by
+synchronously-lifted functions (which return their value by returning from the
+lifted core function).
+
 The `trap_if(result_type != task.ft.results)` guard ensures that, in a
 component with multiple exported functions of different types, `task.return` is
 not called with a mismatched result type (which, due to indirect control flow,
@@ -3428,10 +3434,14 @@ current task have already been dropped (and trapping in `Task.cancel` if not).
 ```python
 async def canon_task_cancel(task):
   trap_if(not task.inst.may_leave)
-  trap_if(task.opts.sync and not task.opts.always_task_return)
+  trap_if(task.opts.sync)
   task.cancel()
   return []
 ```
+The `trap_if(task.opts.sync)` prevents `task.cancel` from being called by
+synchronously-lifted functions (which must always return a value by returning
+from the lifted core function).
+
 `Task.cancel` also traps if there has been no cancellation request (in which
 case the callee expects to receive a return value) or if the task has already
 returned a value or already called `task.cancel`.
@@ -3451,7 +3461,6 @@ Calling `$f` calls `Task.yield_` to allow other tasks to execute:
 ```python
 async def canon_yield(sync, task):
   trap_if(not task.inst.may_leave)
-  trap_if(task.opts.callback and not sync)
   event_code,_,_ = await task.yield_(sync)
   match event_code:
     case EventCode.NONE:
@@ -3469,11 +3478,6 @@ Because other tasks can execute, a subtask can be cancelled while executing
 generators should handle cancellation the same way as when receiving the
 `TASK_CANCELLED` event from `waitable-set.wait`.
 
-The guard preventing `async` use of `task.poll` when a `callback` has
-been used preserves the invariant that producer toolchains using
-`callback` never need to handle multiple overlapping callback
-activations.
-
 
 ### 🔀 `canon waitable-set.new`
 
@@ -3509,7 +3513,6 @@ returning its `EventCode` and writing the payload values into linear memory:
 ```python
 async def canon_waitable_set_wait(sync, mem, task, si, ptr):
   trap_if(not task.inst.may_leave)
-  trap_if(task.opts.callback and not sync)
   s = task.inst.table.get(si)
   trap_if(not isinstance(s, WaitableSet))
   e = await task.wait_for_event(s, sync)
@@ -3533,10 +3536,6 @@ though, the automatic backpressure (applied by `Task.enter`) will ensure there
 is only ever at most once synchronously-lifted task executing in a component
 instance at a time.
 
-The guard preventing `async` use of `wait` when a `callback` has been used
-preserves the invariant that producer toolchains using `callback` never need to
-handle multiple overlapping callback activations.
-
 
 ### 🔀 `canon waitable-set.poll`
 
@@ -3554,7 +3553,6 @@ same way as `wait`.
 ```python
 async def canon_waitable_set_poll(sync, mem, task, si, ptr):
   trap_if(not task.inst.may_leave)
-  trap_if(task.opts.callback and not sync)
   s = task.inst.table.get(si)
   trap_if(not isinstance(s, WaitableSet))
   e = await task.poll_for_event(s, sync)
@@ -3563,10 +3561,6 @@ async def canon_waitable_set_poll(sync, mem, task, si, ptr):
 When `async` is set, `poll_for_event` can yield to other tasks (in this or other
 components) as part of polling for an event.
 
-The guard preventing `async` use of `poll_for_event` when a `callback` has been
-used preserves the invariant that producer toolchains using `callback` never
-need to handle multiple overlapping callback activations.
-
 
 ### 🔀 `canon waitable-set.drop`
 

design/mvp/Explainer.md

@@ -1268,7 +1268,6 @@ canonopt ::= string-encoding=utf8
            | (post-return <core:funcidx>)
            | async 🔀
            | (callback <core:funcidx>) 🔀
-           | always-task-return 🔀
 ```
 While the production `externdesc` accepts any `sort`, the validation rules
 for `canon lift` would only allow the `func` sort. In the future, other sorts
@@ -1326,13 +1325,6 @@ validated to have the following core function type:
 ```
 Again, see the [async explainer] for more details.
 
-🔀 The `always-task-return` option may only be present in `canon lift` when
-`post-return` is not set and specifies that even synchronously-lifted functions
-will call `canon task.return` to return their results instead of returning
-them as core function results. This is a simpler alternative to `post-return`
-for freeing memory after lifting and thus `post-return` may be deprecated in
-the future.
-
 Based on this description of the AST, the [Canonical ABI explainer] gives a
 detailed walkthrough of the static and dynamic semantics of `lift` and `lower`.
 

design/mvp/canonical-abi/definitions.py

@@ -211,7 +211,6 @@ class CanonicalOptions(LiftLowerOptions):
   post_return: Optional[Callable] = None
   sync: bool = True # = !canonopt.async
   callback: Optional[Callable] = None
-  always_task_return: bool = False
 
 ### Runtime State
 
@@ -1865,12 +1864,13 @@ async def canon_lift(opts, inst, ft, callee, caller, on_start, on_resolve, on_bl
 
   if opts.sync:
     flat_results = await call_and_trap_on_throw(callee, task, flat_args)
-    if not opts.always_task_return:
-      assert(types_match_values(flat_ft.results, flat_results))
-      results = lift_flat_values(cx, MAX_FLAT_RESULTS, CoreValueIter(flat_results), ft.result_types())
-      task.return_(results)
-      if opts.post_return is not None:
-        [] = await call_and_trap_on_throw(opts.post_return, task, flat_results)
+    assert(types_match_values(flat_ft.results, flat_results))
+    results = lift_flat_values(cx, MAX_FLAT_RESULTS, CoreValueIter(flat_results), ft.result_types())
+    task.return_(results)
+    if opts.post_return is not None:
+      task.inst.may_leave = False
+      [] = await call_and_trap_on_throw(opts.post_return, task, flat_results)
+      task.inst.may_leave = True
     task.exit()
     return
 
@@ -2043,7 +2043,7 @@ async def canon_backpressure_set(task, flat_args):
 
 async def canon_task_return(task, result_type, opts: LiftOptions, flat_args):
   trap_if(not task.inst.may_leave)
-  trap_if(task.opts.sync and not task.opts.always_task_return)
+  trap_if(task.opts.sync)
   trap_if(result_type != task.ft.results)
   trap_if(not LiftOptions.equal(opts, task.opts))
   cx = LiftLowerContext(opts, task.inst, task)
@@ -2055,15 +2055,14 @@ async def canon_task_return(task, result_type, opts: LiftOptions, flat_args):
 
 async def canon_task_cancel(task):
   trap_if(not task.inst.may_leave)
-  trap_if(task.opts.sync and not task.opts.always_task_return)
+  trap_if(task.opts.sync)
   task.cancel()
   return []
 
 ### 🔀 `canon yield`
 
 async def canon_yield(sync, task):
   trap_if(not task.inst.may_leave)
-  trap_if(task.opts.callback and not sync)
   event_code,_,_ = await task.yield_(sync)
   match event_code:
     case EventCode.NONE:
@@ -2081,7 +2080,6 @@ async def canon_waitable_set_new(task):
 
 async def canon_waitable_set_wait(sync, mem, task, si, ptr):
   trap_if(not task.inst.may_leave)
-  trap_if(task.opts.callback and not sync)
   s = task.inst.table.get(si)
   trap_if(not isinstance(s, WaitableSet))
   e = await task.wait_for_event(s, sync)
@@ -2098,7 +2096,6 @@ def unpack_event(mem, task, ptr, e: EventTuple):
 
 async def canon_waitable_set_poll(sync, mem, task, si, ptr):
   trap_if(not task.inst.may_leave)
-  trap_if(task.opts.callback and not sync)
   s = task.inst.table.get(si)
   trap_if(not isinstance(s, WaitableSet))
   e = await task.poll_for_event(s, sync)