CABI: improve and add cooperative thread built-ins

Author: lukewagner

design/mvp/CanonicalABI.md

@@ -386,34 +386,37 @@ initially in a "suspended" state and must be explicitly "resumed" using one of
 the following 3 thread built-ins. Once the thread is resumed, the thread can
 learn its own index by calling the [`thread.index`] built-in.
 
+TODO: find a place to put [`thread.exit`]
+TODO: work in [`thread.{suspend,yield}-then-promote`] below
+
 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.
+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.
 
 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`).
+and `thread.suspend-then-resume`, 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.suspend-then-resume` 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.suspend-then-resume` 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-then-resume`).
 
 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`).
+to it (via `thread.yield-then-resume`).
 
 ### Thread-Local Storage
 
@@ -466,6 +469,8 @@ For more information, see [`context.get`] in the AST explainer.
 
 ### Blocking
 
+TODO: this section has to be updated
+
 When a thread calls an import using the async ABI, the Component Model
 guarantees that if the callee **blocks**, control flow is immediately returned
 back to the caller. When the callee is implemented by the *host*, what counts as
@@ -506,9 +511,6 @@ type does not contain `async`.
 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
 
 When an `async`-typed function is called with the async ABI and the call
@@ -678,12 +680,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 +715,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 +1538,16 @@ 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.exit`]: Explainer.md#-threadexit
+[`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

@@ -1464,12 +1464,15 @@ canon ::= ...
         | (canon future.drop-readable <typeidx> (core func <id>?)) 🔀
         | (canon future.drop-writable <typeidx> (core func <id>?)) 🔀
         | (canon thread.index (core func <id>?)) 🧵
+        | (canon thread.exit (core func <id>?)) 🧵
         | (canon thread.new-indirect <typeidx> <core:tableidx> (core func <id>?)) 🧵
         | (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>?)) 📝
@@ -2067,6 +2070,23 @@ learn their index via `thread.index`.
 For details, see [Thread Built-ins] in the concurrency explainer and
 [`canon_thread_index`] in the Canonical ABI explainer.
 
+###### 🧵 `thread.exit`
+
+| Synopsis                   |            |
+| -------------------------- | ---------- |
+| Approximate WIT signature  | `func()`   |
+| Canonical ABI signature    | `[] -> []` |
+
+The `thread.exit` built-in immediately exits the [current thread] without
+running any Core WebAssembly handlers on the stack, as-if suspending with a
+[stack-switching] tag not exposed to Core WebAssembly and then dropping the
+generated `contref`. Thus, producer toolchains should be careful to only call
+`thread.exit` when unwinding is not expected (e.g., when calling
+`pthread_exit()`).
+
+For details, see [Thread Built-ins] in the concurrency explainer and
+[`canon_thread_exit`] in the Canonical ABI explainer.
+
 ###### 🧵 `thread.new-indirect`
 
 | Synopsis                   |                                                                       |
@@ -2089,7 +2109,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 +2142,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 +2155,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.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.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_switch_to`] in the Canonical ABI explainer.
+[`canon_thread_suspend_then_resume`] in the Canonical ABI explainer.
 
-###### 🧵 `thread.yield-to`
+###### 🧵 `thread.yield-then-resume`
 
 | 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.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_yield_to`] in the Canonical ABI explainer.
+[`canon_thread_yield_then_resume`] in the Canonical ABI explainer.
+
+###### 🧵 `thread.suspend-then-promote`
+
+| Synopsis                   |                                         |
+| -------------------------- | --------------------------------------- |
+| Approximate WIT signature  | `func<cancellable?>(t: thread) -> bool` |
+| Canonical ABI signature    | `[t:i32] -> [i32]`                      |
+
+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_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`
 
@@ -3282,12 +3320,15 @@ For some use-case-focused, worked examples, see:
 [`canon_error_context_debug_message`]: CanonicalABI.md#-canon-error-contextdebug-message
 [`canon_error_context_drop`]: CanonicalABI.md#-canon-error-contextdrop
 [`canon_thread_index`]: CanonicalABI.md#-canon-threadindex
+[`canon_thread_exit`]: CanonicalABI.md#-canon-threadexit
 [`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