CABI: reorder definitions (no behavior change)

Author: lukewagner

design/mvp/CanonicalABI.md

@@ -61,11 +61,11 @@ specified here.
   * [`canon {stream,future}.drop-{readable,writable}`](#-canon-streamfuturedrop-readablewritable) 🔀
   * [`canon thread.index`](#-canon-threadindex) 🧵
   * [`canon thread.new-indirect`](#-canon-threadnew-indirect) 🧵
-  * [`canon thread.switch-to`](#-canon-threadswitch-to) 🧵
-  * [`canon thread.suspend`](#-canon-threadsuspend) 🧵
   * [`canon thread.resume-later`](#-canon-threadresume-later) 🧵
-  * [`canon thread.yield-to`](#-canon-threadyield-to) 🧵
+  * [`canon thread.suspend`](#-canon-threadsuspend) 🧵
   * [`canon thread.yield`](#-canon-threadyield) 🧵
+  * [`canon thread.switch-to`](#-canon-threadswitch-to) 🧵
+  * [`canon thread.yield-to`](#-canon-threadyield-to) 🧵
   * [`canon error-context.new`](#-canon-error-contextnew) 📝
   * [`canon error-context.debug-message`](#-canon-error-contextdebug-message) 📝
   * [`canon error-context.drop`](#-canon-error-contextdrop) 📝
@@ -4779,34 +4779,30 @@ actually start executing, Core WebAssembly code must call one of the other
 `thread.*` built-ins defined below.
 
 
-### 🧵 `canon thread.switch-to`
+### 🧵 `canon thread.resume-later`
 
 For a canonical definition:
 ```wat
-(canon thread.switch-to $cancellable? (core func $switch-to))
+(canon thread.resume-later (core func $resume-later))
 ```
 validation specifies:
-* `$switch-to` is given type `(func (param $i i32) (result i32))`
+* `$resume-later` is given type `(func (param $i i32))`
 
-Calling `$switch-to` invokes the following function which loads a thread at
+Calling `$resume-later` invokes the following function which loads a thread at
 index `$i` from the current component instance's `threads` table, traps if it's
-not [suspended], and then switches to that thread, leaving the [current thread]
-suspended.
+not [suspended], and then marks that thread as ready to run at some
+nondeterministic point in the future chosen by the embedder.
 ```python
-def canon_thread_switch_to(cancellable, i):
+def canon_thread_resume_later(i):
   thread = current_thread()
   trap_if(not thread.task.inst.may_leave)
   other_thread = thread.task.inst.threads.get(i)
   trap_if(not other_thread.suspended())
-  cancelled = thread.switch_to(cancellable, other_thread)
-  return [cancelled]
+  other_thread.resume_later()
+  return []
 ```
-If `cancellable` is set, then `thread.switch-to` will return a `Cancelled`
-value to indicate whether the supertask has already or concurrently requested
-cancellation. `thread.switch-to` (and other cancellable operations) will only
-indicate cancellation once and thus, if a caller is not prepared to propagate
-cancellation, they can omit `cancellable` so that cancellation is instead
-delivered at a later `cancellable` call.
+`thread.resume-later` never suspends the [current thread] and so there is no
+possibility of cancellation and thus no `cancellable` immediate.
 
 
 ### 🧵 `canon thread.suspend`
@@ -4840,94 +4836,98 @@ cancellation, they can omit `cancellable` so that cancellation is instead
 delivered at a later `cancellable` call.
 
 
-### 🧵 `canon thread.resume-later`
+### 🧵 `canon thread.yield`
 
 For a canonical definition:
 ```wat
-(canon thread.resume-later (core func $resume-later))
+(canon thread.yield $cancellable? (core func $yield))
 ```
 validation specifies:
-* `$resume-later` is given type `(func (param $i i32))`
+* `$yield` is given type `(func (result i32))`
 
-Calling `$resume-later` invokes the following function which loads a thread at
-index `$i` from the current component instance's `threads` table, traps if it's
-not [suspended], and then marks that thread as ready to run at some
-nondeterministic point in the future chosen by the embedder.
+Calling `$yield` invokes the following function which yields execution so that
+others threads can execute, leaving the current thread ready to run at some
+nondeterministic point in the future chosen by the embedder. This allows a
+long-running computation that is not otherwise performing I/O to avoid starving
+other threads in a cooperative setting.
 ```python
-def canon_thread_resume_later(i):
+def canon_thread_yield(cancellable):
   thread = current_thread()
   trap_if(not thread.task.inst.may_leave)
-  other_thread = thread.task.inst.threads.get(i)
-  trap_if(not other_thread.suspended())
-  other_thread.resume_later()
-  return []
+  cancelled = thread.yield_(cancellable)
+  return [cancelled]
 ```
-`thread.resume-later` never suspends the [current thread] and so there is no
-possibility of cancellation and thus no `cancellable` immediate.
+If a non-`async`-typed function export that has not yet returned a value
+transitively calls `thread.yield`, 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.
 
+If `cancellable` is set, then `thread.yield` will return a `Cancelled`
+value indicating whether the supertask has already or concurrently requested
+cancellation. `thread.yield` (and other cancellable operations) will only
+indicate cancellation once and thus, if a caller is not prepared to propagate
+cancellation, they can omit `cancellable` so that cancellation is instead
+delivered at a later `cancellable` call.
 
-### 🧵 `canon thread.yield-to`
+
+### 🧵 `canon thread.switch-to`
 
 For a canonical definition:
 ```wat
-(canon thread.yield-to $cancellable? (core func $yield-to))
+(canon thread.switch-to $cancellable? (core func $switch-to))
 ```
 validation specifies:
-* `$yield-to` is given type `(func (param $i i32) (result i32))`
+* `$switch-to` is given type `(func (param $i i32) (result i32))`
 
-Calling `$yield-to` invokes the following function which loads a thread at
+Calling `$switch-to` invokes the following function which loads a thread at
 index `$i` from the current component instance's `threads` table, traps if it's
 not [suspended], and then switches to that thread, leaving the [current thread]
-ready to run at some nondeterministic point in the future chosen by the
-embedder.
+suspended.
 ```python
-def canon_thread_yield_to(cancellable, i):
+def canon_thread_switch_to(cancellable, i):
   thread = current_thread()
   trap_if(not thread.task.inst.may_leave)
   other_thread = thread.task.inst.threads.get(i)
   trap_if(not other_thread.suspended())
-  cancelled = thread.yield_to(cancellable, other_thread)
+  cancelled = thread.switch_to(cancellable, other_thread)
   return [cancelled]
 ```
-If `cancellable` is set, then `thread.yield-to` will return a `Cancelled`
-value indicating whether the supertask has already or concurrently requested
-cancellation. `thread.yield-to` (and other cancellable operations) will only
+If `cancellable` is set, then `thread.switch-to` will return a `Cancelled`
+value to indicate whether the supertask has already or concurrently requested
+cancellation. `thread.switch-to` (and other cancellable operations) will only
 indicate cancellation once and thus, if a caller is not prepared to propagate
 cancellation, they can omit `cancellable` so that cancellation is instead
 delivered at a later `cancellable` call.
 
 
-### 🧵 `canon thread.yield`
+### 🧵 `canon thread.yield-to`
 
 For a canonical definition:
 ```wat
-(canon thread.yield $cancellable? (core func $yield))
+(canon thread.yield-to $cancellable? (core func $yield-to))
 ```
 validation specifies:
-* `$yield` is given type `(func (result i32))`
+* `$yield-to` is given type `(func (param $i i32) (result i32))`
 
-Calling `$yield` invokes the following function which yields execution so that
-others threads can execute, leaving the current thread ready to run at some
-nondeterministic point in the future chosen by the embedder. This allows a
-long-running computation that is not otherwise performing I/O to avoid starving
-other threads in a cooperative setting.
+Calling `$yield-to` invokes the following function which loads a thread at
+index `$i` from the current component instance's `threads` table, traps if it's
+not [suspended], and then switches to that thread, leaving the [current thread]
+ready to run at some nondeterministic point in the future chosen by the
+embedder.
 ```python
-def canon_thread_yield(cancellable):
+def canon_thread_yield_to(cancellable, i):
   thread = current_thread()
   trap_if(not thread.task.inst.may_leave)
-  cancelled = thread.yield_(cancellable)
+  other_thread = thread.task.inst.threads.get(i)
+  trap_if(not other_thread.suspended())
+  cancelled = thread.yield_to(cancellable, other_thread)
   return [cancelled]
 ```
-If a non-`async`-typed function export that has not yet returned a value
-transitively calls `thread.yield`, 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.
-
-If `cancellable` is set, then `thread.yield` will return a `Cancelled`
+If `cancellable` is set, then `thread.yield-to` will return a `Cancelled`
 value indicating whether the supertask has already or concurrently requested
-cancellation. `thread.yield` (and other cancellable operations) will only
+cancellation. `thread.yield-to` (and other cancellable operations) will only
 indicate cancellation once and thus, if a caller is not prepared to propagate
 cancellation, they can omit `cancellable` so that cancellation is instead
 delivered at a later `cancellable` call.

design/mvp/Explainer.md

@@ -1458,11 +1458,11 @@ canon ::= ...
         | (canon future.drop-writable <typeidx> (core func <id>?)) 🔀
         | (canon thread.index (core func <id>?)) 🧵
         | (canon thread.new-indirect <typeidx> <core:tableidx> (core func <id>?)) 🧵
-        | (canon thread.switch-to cancellable? (core func <id>?)) 🧵
-        | (canon thread.suspend cancellable? (core func <id>?)) 🧵
         | (canon thread.resume-later (core func <id>?)) 🧵
-        | (canon thread.yield-to cancellable? (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 error-context.new <canonopt>* (core func <id>?)) 📝
         | (canon error-context.debug-message <canonopt>* (core func <id>?)) 📝
         | (canon error-context.drop (core func <id>?)) 📝
@@ -2101,29 +2101,19 @@ eagerly or lazily by [`thread.yield-to`](#-threadyield-to) or
 For details, see [Thread Built-ins] in the concurrency explainer and
 [`canon_thread_new_indirect`] in the Canonical ABI explainer.
 
-###### 🧵 `thread.switch-to`
-
-| Synopsis                   |                                         |
-| -------------------------- | --------------------------------------- |
-| Approximate WIT signature  | `func<cancellable?>(t: thread) -> bool` |
-| Canonical ABI signature    | `[t:i32] -> [i32]`                      |
+###### 🧵 `thread.resume-later`
 
-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`.
+| Synopsis                   |                   |
+| -------------------------- | ----------------- |
+| Approximate WIT signature  | `func(t: thread)` |
+| Canonical ABI signature    | `[t:i32] -> []`   |
 
-If `thread.switch-to` is called from a synchronous- or `async callback`-lifted
-export, no other threads that were implicitly created by a separate
-synchronous- or `async callback`-lifted export call can start or progress in
-the current component instance until `thread.switch-to` returns (thereby
-ensuring non-reentrance of the core wasm code). However, explicitly-created
-threads and threads implicitly created by non-`callback` `async`-lifted
-("stackful async") exports may start or progress at any time.
+The `thread.resume-later` built-in changes the state of thread `t` from
+"suspended" to "ready" (trapping if `t` is not in a "suspended" state) so that
+the runtime can nondeterministically resume `t` at some point in the future.
 
 For details, see [Thread Built-ins] in the concurrency explainer and
-[`canon_thread_switch_to`] in the Canonical ABI explainer.
+[`canon_thread_resume_later`] in the Canonical ABI explainer.
 
 ###### 🧵 `thread.suspend`
 
@@ -2150,69 +2140,79 @@ threads and threads implicitly created by non-`callback` `async`-lifted
 For details, see [Thread Built-ins] in the concurrency explainer and
 [`canon_thread_suspend`] in the Canonical ABI explainer.
 
-###### 🧵 `thread.resume-later`
+###### 🧵 `thread.yield`
 
-| Synopsis                   |                   |
-| -------------------------- | ----------------- |
-| Approximate WIT signature  | `func(t: thread)` |
-| Canonical ABI signature    | `[t:i32] -> []`   |
+| Synopsis                   |                                |
+| -------------------------- | ------------------------------ |
+| Approximate WIT signature  | `func<cancellable?>() -> bool` |
+| Canonical ABI signature    | `[] -> [i32]`                  |
 
-The `thread.resume-later` built-in changes the state of thread `t` from
-"suspended" to "ready" (trapping if `t` is not in a "suspended" state) so that
-the runtime can nondeterministically resume `t` at some point in the future.
+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, no other threads that were implicitly created by a separate
+synchronous- or `async callback`-lifted export call can start or progress in
+the current component instance until `thread.yield` returns (thereby
+ensuring non-reentrance of the core wasm code). However, explicitly-created
+threads and threads implicitly created by non-`callback` `async`-lifted
+("stackful async") exports may start or progress at any time.
 
 For details, see [Thread Built-ins] in the concurrency explainer and
-[`canon_thread_resume_later`] in the Canonical ABI explainer.
+[`canon_thread_yield`] in the Canonical ABI explainer.
 
-###### 🧵 `thread.yield-to`
+###### 🧵 `thread.switch-to`
 
 | 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.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`.
 
-If `thread.yield-to` is called from a synchronous- or `async callback`-lifted
+If `thread.switch-to` is called from a synchronous- or `async callback`-lifted
 export, no other threads that were implicitly created by a separate
 synchronous- or `async callback`-lifted export call can start or progress in
-the current component instance until `thread.yield-to` returns (thereby
+the current component instance until `thread.switch-to` returns (thereby
 ensuring non-reentrance of the core wasm code). However, explicitly-created
 threads and threads implicitly created by non-`callback` `async`-lifted
 ("stackful async") exports may start or progress at any time.
 
 For details, see [Thread Built-ins] in the concurrency explainer and
-[`canon_thread_yield_to`] in the Canonical ABI explainer.
+[`canon_thread_switch_to`] in the Canonical ABI explainer.
 
-###### 🧵 `thread.yield`
+###### 🧵 `thread.yield-to`
 
-| Synopsis                   |                                |
-| -------------------------- | ------------------------------ |
-| Approximate WIT signature  | `func<cancellable?>() -> bool` |
-| Canonical ABI signature    | `[] -> [i32]`                  |
+| Synopsis                   |                                         |
+| -------------------------- | --------------------------------------- |
+| Approximate WIT signature  | `func<cancellable?>(t: thread) -> bool` |
+| Canonical ABI signature    | `[t:i32] -> [i32]`                      |
 
-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`.
+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`.
 
-If `thread.yield` is called from a synchronous- or `async callback`-lifted
+If `thread.yield-to` is called from a synchronous- or `async callback`-lifted
 export, no other threads that were implicitly created by a separate
 synchronous- or `async callback`-lifted export call can start or progress in
-the current component instance until `thread.yield` returns (thereby
+the current component instance until `thread.yield-to` returns (thereby
 ensuring non-reentrance of the core wasm code). However, explicitly-created
 threads and threads implicitly created by non-`callback` `async`-lifted
 ("stackful async") exports may start or progress at any time.
 
 For details, see [Thread Built-ins] in the concurrency explainer and
-[`canon_thread_yield`] in the Canonical ABI explainer.
+[`canon_thread_yield_to`] in the Canonical ABI explainer.
 
 ###### 🧵② `thread.spawn-ref`