CABI: improve and add cooperative thread built-ins

Author: lukewagner

design/mvp/CanonicalABI.md

@@ -388,32 +388,43 @@ learn its own index by calling the [`thread.index`] built-in.
 
 A suspended thread (identified by thread-table index) can be resumed at some
 nondeterministic point in future via the [`thread.resume-later`] built-in. In
-contrast, the [`thread.yield-to`] built-in switches execution to the given
-thread immediately, leaving the *calling* thread to be resumed at some
-nondeterministic point in the future. Lastly, the [`thread.switch-to`]
-built-in switches execution to the given thread immediately, like `yield-to`,
-but leaves the calling thread in the "suspended" state. These three functions
-can be used to resume both newly-created threads as well as threads that
-executed and then suspended.
-
-In addition to threads entering the suspended state via `thread.new-indirect`
-and `thread.switch-to`, threads can also explicitly suspend themselves via the
-[`thread.suspend`] built-in. Thus, there are three ways a thread *enters* the
-suspended state and three ways a thread *exits* the suspended state (with
-`thread.switch-to` serving in both categories). Together, these 5 thread
-built-ins support both the "green thread" [use cases](#goals) where Core
-WebAssembly code running inside the component wants to fully control thread
-scheduling (via `thread.switch-to` and `thread.suspend`) as well as the "host
-thread" use cases where the Core WebAssembly code wants to let the containing
-runtime nondeterministically schedule threads (via `thread.resume-later` or
-`thread.yield-to`).
-
-Lastly, since threads are cooperative, there is a [`thread.yield`] built-in
-that can be called in the middle of long-running computations to allow the
-runtime to nondeterministically switch execution to another thread.
-`thread.yield` is equivalent to (but obviously more efficient than) creating a
-new thread with a no-op function (via `thread.new-indirect`) and then yielding
-to it (via `thread.yield-to`).
+contrast, the [`thread.yield-then-resume`] built-in switches execution to the
+given thread immediately, leaving the *calling* thread to be resumed at some
+nondeterministic point in the future. Lastly, the [`thread.suspend-then-resume`]
+built-in switches execution to the given thread immediately, like
+`thread.yield-then-resume`, but leaves the calling thread in the "suspended"
+state. These three functions can be used to resume both newly-created threads as
+well as threads that executed and then suspended.
+
+Threads can also explicitly put themselves in the "suspended" state without
+specifying the other thread to run by calling the [`thread.suspend`] built-in.
+This is useful if a thread needs to wait on some condition that will be met by
+some unknown thread in the future (which will resume the suspended thread).
+Similarly, threads can explicitly put themselves in the "ready to run" state
+without specifying the other thread to run by calling [`thread.yield`]. This is
+useful if a thread has a long-running computation without I/O but still needs to
+allow other cooperative threads to make progress concurrently.
+
+Lastly, in addition to being able to switch to "suspended" threads, threads can
+also switch to threads that are in a "ready to run" state by calling the
+[`thread.suspend-then-promote`] and [`thread.yield-then-promote`] built-ins
+which, like the `thread.{suspend,yield}-then-resume` built-ins, leave the
+calling thread in a "suspended" or "ready to run" state, resp. While the calling
+thread *may* know that the target thread is ready to run (e.g., because the
+target thread yielded or is waiting on a future/stream operation that the
+calling thread just completed), in general readiness may depend on
+nondeterministic external I/O and the calling thread just wants to yield its
+timeslice to the target thread *if* it's ready. Thus, if the target thread
+is *not* "ready to run", these built-ins fall back to the behavior of the
+untargeted `thread.{suspend,yield}` built-ins.
+
+Together, these thread built-ins support both the "green thread" [use
+cases](#goals), where Core WebAssembly code running inside the component wants
+to fully control thread scheduling (via the suspending and resuming built-ins)
+as well as the "host thread" use cases where the Core WebAssembly code wants to
+let the containing runtime nondeterministically schedule threads (via yielding
+and promoting built-ins).
+
 
 ### Thread-Local Storage
 
@@ -475,39 +486,56 @@ traditional synchronous OS syscalls or an asynchronous `io_uring`. However,
 when the callee is implemented by another component, the Component Model
 defines exactly what counts as "blocking".
 
-At a high level, there are six ways for a call to a component export to block,
-all of which are described above or below in more detail:
-* calling an `async`-typed function import using the sync ABI
+There are several ways for the [task](#threads-and-tasks) created by calling a
+component export to potentially block:
 * suspending the current thread via the
-  [`thread.suspend`](#thread-built-ins) built-in
+  [`thread.suspend{,then-promote}`](#thread-built-ins) built-ins
 * cooperatively yielding (e.g., during a long-running computation) via the
-  [`thread.yield`](#thread-built-ins) built-in
+  [`thread.yield{,-then-promote}`](#thread-built-ins) built-ins
 * waiting for one of a set of concurrent operations to complete via the
   [`waitable-set.wait`](#waitables-and-waitable-sets) built-in
-* waiting for a stream or future operation to complete via the
+* synchronously waiting for a stream or future operation to complete via the
   [`{stream,future}.{,cancel-}{read,write}`](#streams-and-futures) built-ins
-* waiting for a subtask to cooperatively cancel itself via the
+* synchronously waiting for a subtask to cooperatively cancel itself via the
   [`subtask.cancel`](#cancellation) built-in
+* synchronously calling an `async` function (which may transitively block)
+
+At each of these points, the [current thread](#current-thread-and-task) may
+block and be suspended, depending on the operation and the state of the world.
+Thus, each of these represents **cooperative yield points**.
+
+If the [current task](#current-thread-and-task) has already returned its value
+to the caller, then control flow is transferred back to the caller, which can
+now use the return value that was written to memory via the ABI.
+
+However, if the current task has *not* yet returned a value, the behavior
+depends on the *function type* of the callee:
+
+If the callee's function type is `async`, then the task is also considered to
+"block". According to the async ABI, control flow is then transferred to the
+innermost caller using the async ABI (noting that there may be any number of
+sync ABI calls on the stack between the innermost async ABI caller and the
+blocking callee).
+
+
+If instead the callee's function type is *not* `async`, then 
 
-At each of these points, the [current thread](#current-thread-and-task) will be
+"blocked" if there is some other thread in the same component instance that
+is in the ["ready to run"](#thread-built-ins) state. In this case, the runtime
+switches to another thread (picking nondeterministically if there are multiple
+ready threads) and continues doing so until either
+
+
+However, the
+operation 
 suspended. Execution transfers to a caller's thread if there is one, or
 otherwise back to the runtime, which may invoke new component exports or
-nondeterministically resume a cooperative thread that is ready to run. Thus,
-each of these represents **cooperative yield points**.
-
-Additionally, each of these potentially-blocking operations will trap if the
-[current task's function type](#current-thread-and-task) does not declare the
-`async` effect, since only `async`-typed functions are allowed to block. As an
-exception, to allow it to be called arbitrarily from anywhere, `thread.yield`
-does not trap but instead behaves as a no-op if the current task's function
-type does not contain `async`.
+nondeterministically resume a cooperative thread that is ready to run. 
 
 "Blocking" is [specified in terms of] stack-switching, with a `block` effect
 that suspends the current thread to produce a continuation that can be resumed
 once the reason for blocking is addressed.
 
-The [Canonical ABI explainer] defines the above behavior more precisely; search
-for `may_block` to see all the relevant points.
 
 ### Waitables and Waitable Sets
 
@@ -678,12 +706,12 @@ degree of concurrency than synchronous exports. Stackful async exports ignore
 the lock entirely and thus achieve the highest degree of (cooperative)
 concurrency.
 
-Since non-`async` functions are not allowed to block (including due to
-backpressure) and also don't pile up like `async` functions, non-`async`
-functions ignore backpressure (explicit and implicit) entirely. If a
-component exports a mix of `async` and non-`async` functions, code generation
-must therefore be prepared to handle non-`async` functions executing at
-any cooperative yield point, even in the middle of a `callback`.
+Since non-`async` functions are not allowed to [block](#blocking) (including due
+to backpressure) and also don't pile up like `async` functions, non-`async`
+functions ignore backpressure (explicit and implicit) entirely. If a component
+exports a mix of `async` and non-`async` functions, code generation must
+therefore be prepared to handle non-`async` functions executing at any
+cooperative yield point, even in the middle of a `callback`.
 
 Once a task is allowed to start according to these backpressure rules, its
 arguments are lowered into the callee's linear memory and the task is in
@@ -713,9 +741,7 @@ the readable end passed for `in`) and `stream.write`s (of the writable end it
 `stream.new`ed) before exiting the task.
 
 Once `task.return` is called, the task is in the "returned" state. Calling
-`task.return` when not in the "started" state traps. Once in a "returned" state,
-non-`async` functions may block using cooperative threads that were created
-before the synchronous task's implicit thread returned.
+`task.return` when not in the "started" state traps.
 
 ### Borrows
 
@@ -1538,13 +1564,15 @@ comes after:
 [`waitable-set.wait`]: Explainer.md#-waitable-setwait
 [`waitable-set.poll`]: Explainer.md#-waitable-setpoll
 [`waitable.join`]: Explainer.md#-waitablejoin
-[`thread.new-indirect`]: Explainer.md#-threadnew-indirect
 [`thread.index`]: Explainer.md#-threadindex
-[`thread.suspend`]: Explainer.md#-threadsuspend
-[`thread.switch-to`]: Explainer.md#-threadswitch-to
+[`thread.new-indirect`]: Explainer.md#-threadnew-indirect
 [`thread.resume-later`]: Explainer.md#-threadresume-later
-[`thread.yield-to`]: Explainer.md#-threadyield-to
+[`thread.suspend`]: Explainer.md#-threadsuspend
 [`thread.yield`]: Explainer.md#-threadyield
+[`thread.suspend-then-resume`]: Explainer.md#-threadsuspend-then-resume
+[`thread.yield-then-resume`]: Explainer.md#-threadyield-then-resume
+[`thread.suspend-then-promote`]: Explainer.md#-threadsuspend-then-promote
+[`thread.yield-then-promote`]: Explainer.md#-threadyield-then-promote
 [`{stream,future}.new`]: Explainer.md#-streamnew-and-futurenew
 [`{stream,future}.{read,write}`]: Explainer.md#-streamread-and-streamwrite
 [`stream.cancel-write`]: Explainer.md#-streamcancel-read-streamcancel-write-futurecancel-read-and-futurecancel-write

design/mvp/Concurrency.md

@@ -1468,8 +1468,10 @@ canon ::= ...
         | (canon thread.resume-later (core func <id>?)) 🧵
         | (canon thread.suspend cancellable? (core func <id>?)) 🧵
         | (canon thread.yield cancellable? (core func <id>?)) 🔀
-        | (canon thread.switch-to cancellable? (core func <id>?)) 🧵
-        | (canon thread.yield-to cancellable? (core func <id>?)) 🧵
+        | (canon thread.suspend-then-resume cancellable? (core func <id>?)) 🧵
+        | (canon thread.yield-then-resume cancellable? (core func <id>?)) 🧵
+        | (canon thread.suspend-then-promote cancellable? (core func <id>?)) 🧵
+        | (canon thread.yield-then-promote cancellable? (core func <id>?)) 🧵
         | (canon error-context.new <canonopt>* (core func <id>?)) 📝
         | (canon error-context.debug-message <canonopt>* (core func <id>?)) 📝
         | (canon error-context.drop (core func <id>?)) 📝
@@ -2089,7 +2091,7 @@ extended for [GC].
 
 As explained in the [concurrency explainer], a thread created by
 `thread.new-indirect` is initially in a suspended state and must be resumed
-eagerly or lazily by [`thread.yield-to`](#-threadyield-to) or
+eagerly or lazily by [`thread.yield-then-resume`](#-threadyield-then-resume) or
 [`thread.resume-later`](#-threadresume-later), resp., to begin execution.
 
 For details, see [Thread Built-ins] in the concurrency explainer and
@@ -2122,9 +2124,6 @@ explicitly resumed by some other thread calling a built-in such as
 the current task was [cancelled] by the caller; otherwise, `thread.suspend`
 always returns `false`.
 
-A non-`async`-typed function export that has not yet returned a value traps if
-it transitively attempts to call `thread.suspend`.
-
 For details, see [Thread Built-ins] in the concurrency explainer and
 [`canon_thread_suspend`] in the Canonical ABI explainer.
 
@@ -2138,52 +2137,73 @@ For details, see [Thread Built-ins] in the concurrency explainer and
 The `thread.yield` built-in allows the runtime to potentially switch to any
 other thread in the "ready" state, enabling a long-running computation to
 cooperatively interleave execution without specifically requesting another
-thread to be resumed (as with `thread.yield-to`). If `cancellable` is set,
-`thread.yield` returns whether the current task was [cancelled] by the caller;
-otherwise, `thread.yield` always returns `false`.
-
-If `thread.yield` is called from a synchronous- or `async callback`-lifted
-export, it returns immediately without blocking (instead of trapping, as with
-other possibly-blocking operations like `waitable-set.wait`). This is because,
-unlike other built-ins, `thread.yield` may be scattered liberally throughout
-code that might show up in the transitive call tree of a synchronous function
-call.
+thread to be resumed (as with `thread.yield-then-resume`). If `cancellable` is
+set, `thread.yield` returns whether the current task was [cancelled] by the
+caller; otherwise, `thread.yield` always returns `false`.
 
 For details, see [Thread Built-ins] in the concurrency explainer and
 [`canon_thread_yield`] in the Canonical ABI explainer.
 
-###### 🧵 `thread.switch-to`
+###### 🧵 `thread.suspend-then-resume`
+
+| Synopsis                   |                                         |
+| -------------------------- | --------------------------------------- |
+| Approximate WIT signature  | `func<cancellable?>(t: thread) -> bool` |
+| Canonical ABI signature    | `[t:i32] -> [i32]`                      |
+
+The `thread.suspend-then-resume` built-in suspends the [current thread] and
+immediately resumes execution of the thread `t`, trapping if `t` is not in a
+"suspended" state. If `cancellable` is set, `thread.suspend-then-resume` returns
+whether the current task was [cancelled] by the caller; otherwise,
+`thread.suspend-then-resume` always returns `false`.
+
+For details, see [Thread Built-ins] in the concurrency explainer and
+[`canon_thread_suspend_then_resume`] in the Canonical ABI explainer.
+
+###### 🧵 `thread.yield-then-resume`
 
 | Synopsis                   |                                         |
 | -------------------------- | --------------------------------------- |
 | Approximate WIT signature  | `func<cancellable?>(t: thread) -> bool` |
 | Canonical ABI signature    | `[t:i32] -> [i32]`                      |
 
-The `thread.switch-to` built-in suspends the [current thread] and immediately
-resumes execution of the thread `t`, trapping if `t` is not in a "suspended"
-state. If `cancellable` is set, `thread.switch-to` returns whether the current
-task was [cancelled] by the caller; otherwise, `thread.switch-to` always returns
-`false`.
+The `thread.yield-then-resume` built-in immediately resumes execution of the
+thread `t`, (trapping if `t` is not in a "suspended" state) leaving the [current
+thread] in a "ready" state so that the runtime can nondeterministically resume
+the current thread at some point in the future. If `cancellable` is set,
+`thread.yield-then-resume` returns whether the current task was [cancelled] by
+the caller; otherwise, `thread.yield-then-resume` always returns `false`.
 
 For details, see [Thread Built-ins] in the concurrency explainer and
-[`canon_thread_switch_to`] in the Canonical ABI explainer.
+[`canon_thread_yield_then_resume`] in the Canonical ABI explainer.
 
-###### 🧵 `thread.yield-to`
+###### 🧵 `thread.suspend-then-promote`
 
 | Synopsis                   |                                         |
 | -------------------------- | --------------------------------------- |
 | Approximate WIT signature  | `func<cancellable?>(t: thread) -> bool` |
 | Canonical ABI signature    | `[t:i32] -> [i32]`                      |
 
-The `thread.yield-to` built-in immediately resumes execution of the thread `t`,
-(trapping if `t` is not in a "suspended" state) leaving the [current thread] in
-a "ready" state so that the runtime can nondeterministically resume the current
-thread at some point in the future. If `cancellable` is set, `thread.yield-to`
-returns whether the current task was [cancelled] by the caller; otherwise,
-`thread.yield-to` always returns `false`.
+The `thread.suspend-then-promote` built-in immediately resumes execution of the
+thread `t` if `t` is in a "ready" state, in any case leaving the current thread
+in a "suspended" state.
 
 For details, see [Thread Built-ins] in the concurrency explainer and
-[`canon_thread_yield_to`] in the Canonical ABI explainer.
+[`canon_thread_suspend_then_promote`] in the Canonical ABI explainer.
+
+###### 🧵 `thread.yield-then-promote`
+
+| Synopsis                   |                                         |
+| -------------------------- | --------------------------------------- |
+| Approximate WIT signature  | `func<cancellable?>(t: thread) -> bool` |
+| Canonical ABI signature    | `[t:i32] -> [i32]`                      |
+
+The `thread.yield-then-promote` built-in immediately resumes execution of the
+thread `t` if `t` is in a "ready" state, in any case leaving the current thread
+in a "ready" state.
+
+For details, see [Thread Built-ins] in the concurrency explainer and
+[`canon_thread_yield_then_promote`] in the Canonical ABI explainer.
 
 ###### 🧵② `thread.spawn-ref`
 
@@ -3283,11 +3303,13 @@ For some use-case-focused, worked examples, see:
 [`canon_error_context_drop`]: CanonicalABI.md#-canon-error-contextdrop
 [`canon_thread_index`]: CanonicalABI.md#-canon-threadindex
 [`canon_thread_new_indirect`]: CanonicalABI.md#-canon-threadnew-indirect
-[`canon_thread_suspend`]: CanonicalABI.md#-canon-threadsuspend
-[`canon_thread_switch_to`]: CanonicalABI.md#-canon-threadswitch-to
 [`canon_thread_resume_later`]: CanonicalABI.md#-canon-threadresume-later
-[`canon_thread_yield_to`]: CanonicalABI.md#-canon-threadyield-to
+[`canon_thread_suspend`]: CanonicalABI.md#-canon-threadsuspend
 [`canon_thread_yield`]: CanonicalABI.md#-canon-threadyield
+[`canon_thread_suspend_then_resume`]: CanonicalABI.md#-canon-threadsuspend-then-resume
+[`canon_thread_yield_then_resume`]: CanonicalABI.md#-canon-threadyield-then-resume
+[`canon_thread_suspend_then_promote`]: CanonicalABI.md#-canon-threadsuspend-then-promote
+[`canon_thread_yield_then_promote`]: CanonicalABI.md#-canon-threadyield-then-promote
 [`canon_thread_spawn_ref`]: CanonicalABI.md#-canon-threadspawn-ref
 [`canon_thread_spawn_indirect`]: CanonicalABI.md#-canon-threadspawn-indirect
 [`canon_thread_available_parallelism`]: CanonicalABI.md#-canon-threadavailable_parallelism