Tidy CABI: change order of definitions (no behavior change)

Author: lukewagner

design/mvp/CanonicalABI.md

@@ -60,11 +60,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) 📝
@@ -4632,33 +4632,29 @@ 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, thread, i):
+def canon_thread_resume_later(thread, i):
   trap_if(not thread.task.inst.may_leave)
   other_thread = thread.task.inst.threads.get(i)
   trap_if(not other_thread.suspended())
-  resume_arg = thread.switch_to(cancellable, other_thread)
-  return [resume_arg]
+  other_thread.resume_later()
+  return []
 ```
-If `cancellable` is set, then `thread.switch-to` will return a `ResumeArg` 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`
@@ -4691,91 +4687,95 @@ 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(thread, i):
+def canon_thread_yield(cancellable, 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 []
+  resume_arg = thread.yield_(cancellable)
+  return [resume_arg]
 ```
-`thread.resume-later` never suspends the [current thread] and so there is no
-possibility of cancellation and thus no `cancellable` immediate.
+If called during a non-`async`-typed function export, this function does not
+trap. Instead, `Thread.yield_` will simply return without blocking. This allows
+`thread.yield` calls to be sprinkled liberally throughout code. Furthermore,
+even when called from an `async`-typed function export, `Thread.yield_`
+nondeterministically allows the embedder to continue executing the current thread
+based on heuristics (like timing).
 
+If `cancellable` is set, then `thread.yield` will return a `ResumeArg` 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, thread, i):
+def canon_thread_switch_to(cancellable, thread, i):
   trap_if(not thread.task.inst.may_leave)
   other_thread = thread.task.inst.threads.get(i)
   trap_if(not other_thread.suspended())
-  resume_arg = thread.yield_to(cancellable, other_thread)
+  resume_arg = thread.switch_to(cancellable, other_thread)
   return [resume_arg]
 ```
-If `cancellable` is set, then `thread.yield-to` will return a `ResumeArg` 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 `ResumeArg` 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, thread):
+def canon_thread_yield_to(cancellable, thread, i):
   trap_if(not thread.task.inst.may_leave)
-  resume_arg = thread.yield_(cancellable)
+  other_thread = thread.task.inst.threads.get(i)
+  trap_if(not other_thread.suspended())
+  resume_arg = thread.yield_to(cancellable, other_thread)
   return [resume_arg]
 ```
-If called during a non-`async`-typed function export, this function does not
-trap. Instead, `Thread.yield_` will simply return without blocking. This allows
-`thread.yield` calls to be sprinkled liberally throughout code. Furthermore,
-even when called from an `async`-typed function export, `Thread.yield_`
-nondeterministically allows the embedder to continue executing the current thread
-based on heuristics (like timing).
-
-If `cancellable` is set, then `thread.yield` will return a `ResumeArg` value
+If `cancellable` is set, then `thread.yield-to` will return a `ResumeArg` 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

@@ -1456,11 +1456,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>?)) 📝
@@ -2099,34 +2099,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) -> suspend-result` |
-| Canonical ABI signature    | `[t:i32] -> [i32]`                                |
-
-where `suspend-result` is defined in WIT as:
-```wit
-enum suspend-result { completed, cancelled }
-```
+###### 🧵 `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. When the current thread is resumed by some other thread or,
-if `cancellable` was set, [cancellation], `thread.switch-to` will return,
-indicating what happened.
+| 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`
 
@@ -2153,19 +2138,59 @@ 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?>() -> suspend-result` |
+| 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.
+where `suspend-result` is defined in WIT as:
+```wit
+enum suspend-result { completed, cancelled }
+```
+
+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`). When the current thread is
+resumed either due to runtime scheduling or, if `cancellable` was set,
+[cancellation], `thread.yield` will return, indicating what happened.
+
+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.switch-to`
+
+| Synopsis                   |                                                   |
+| -------------------------- | ------------------------------------------------- |
+| Approximate WIT signature  | `func<cancellable?>(t: thread) -> suspend-result` |
+| 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. When the current thread is resumed by some other thread or,
+if `cancellable` was set, [cancellation], `thread.switch-to` will return,
+indicating what happened.
+
+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.
+
+For details, see [Thread Built-ins] in the concurrency explainer and
+[`canon_thread_switch_to`] in the Canonical ABI explainer.
 
 ###### 🧵 `thread.yield-to`
 
@@ -2192,31 +2217,6 @@ threads and threads implicitly created by non-`callback` `async`-lifted
 For details, see [Thread Built-ins] in the concurrency explainer and
 [`canon_thread_yield_to`] in the Canonical ABI explainer.
 
-###### 🧵 `thread.yield`
-
-| Synopsis                   |                                          |
-| -------------------------- | ---------------------------------------- |
-| Approximate WIT signature  | `func<cancellable?>() -> suspend-result` |
-| Canonical ABI signature    | `[] -> [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`). When the current thread is
-resumed either due to runtime scheduling or, if `cancellable` was set,
-[cancellation], `thread.yield` will return, indicating what happened.
-
-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_yield`] in the Canonical ABI explainer.
-
 ###### 🧵② `thread.spawn-ref`
 
 | Synopsis                   |                                                                                            |