Editorial: refactor and explain spin the event loop

This makes the algorithm more explicit, with properly-nested in parallel
and task queuing steps. In particular, it makes it clear (with examples)
how it is a "spec macro".

Co-Authored-By: Anne van Kesteren <annevk@annevk.nl>
Co-Authored-By: Domenic Denicola <d@domenic.me>

Author: annevk

source

@@ -90045,7 +90045,8 @@ dictionary <dfn>PromiseRejectionEventInit</dfn> : <span>EventInit</span> {
 
   <hr>
 
-  <p>When an algorithm says to <dfn>spin the event loop</dfn> until a condition <var>goal</var> is met, the user agent must run the following steps:</p>
+  <p>Algorithm steps that say to <dfn>spin the event loop</dfn> until a condition <var>goal</var> is
+  met are equivalent to substituting in the following algorithm steps:</p>
 
   <ol>
    <li>
@@ -90071,23 +90072,161 @@ dictionary <dfn>PromiseRejectionEventInit</dfn> : <span>EventInit</span> {
    </li>
 
    <li>
-    <p>Stop <var>task</var>, allowing whatever algorithm that invoked it to resume, but continue
-    these steps <span>in parallel</span>.</p>
+    <p><span>In parallel</span>:</p>
+
+    <ol>
+     <li><p>Wait until the condition <var>goal</var> is met.</p></li>
+
+     <li>
+      <p><span>Queue a task</span> on <var>task source</var> to:</p>
+
+      <ol>
+       <li><p>Replace the <span>JavaScript execution context stack</span> with <var>old
+       stack</var>.</p></li>
+
+       <li>
+        <p>Perform any steps that appear after this <span>spin the event loop</span> instance in the
+        original algorithm.</p>
+
+        <p class="note">This resumes <var>task</var>.</p>
+       </li>
+      </ol>
+     </li>
+    </ol>
+   </li>
+
+   <li>
+    <p>Stop <var>task</var>, allowing whatever algorithm that invoked it to resume.</p>
 
     <p class="note">This causes the <span>event loop</span>'s main set of steps or the <span>perform
     a microtask checkpoint</span> algorithm to continue.</p>
    </li>
+  </ol>
 
-   <li><p>Wait until the condition <var>goal</var> is met.</p></li>
+  <p class="note">Unlike other algorithms in this and other specifications, which behave similar to
+  programming-language function calls, <span>spin the event loop</span> is more like a macro, which
+  saves typing and indentation at the usage site by expanding into a series of steps and
+  operations.</p>
 
-   <li><p><span>Queue a task</span> to continue running these steps, on <var>task source</var>. Wait
-   until this new task runs before continuing these steps.</p></li>
+  <div class="example">
+   <p>An algorithm whose steps are:</p>
 
-   <li><p>Replace the <span>JavaScript execution context stack</span> with the <var>old
-   stack</var>.</p></li>
+   <ol>
+    <li><p>Do something.</p></li>
 
-   <li><p>Return to the caller.</p></li>
-  </ol>
+    <li><p><span>Spin the event loop</span> until awesomeness happens.</p></li>
+
+    <li><p>Do something else.</p></li>
+   </ol>
+
+   <p>is a shorthand which, after "macro expansion", becomes</p>
+
+   <ol>
+    <li><p>Do something.</p></li>
+
+    <li><p>Let <var>old stack</var> be a copy of the <span>JavaScript execution context
+    stack</span>.</p></li>
+
+    <li><p>Empty the <span>JavaScript execution context stack</span>.</p></li>
+
+    <li><p><span>Perform a microtask checkpoint</span>.</p></li>
+
+    <li>
+     <p><span>In parallel</span>:</p>
+
+     <ol>
+      <li><p>Wait until awesomeness happens.</p></li>
+
+      <li>
+       <p><span>Queue a task</span> on the task source in which "do something" was done to:</p>
+
+       <ol>
+        <li><p>Replace the <span>JavaScript execution context stack</span> with <var>old
+        stack</var>.</p></li>
+
+        <li><p>Do something else.</p></li>
+       </ol>
+      </li>
+     </ol>
+    </li>
+   </ol>
+  </div>
+
+  <div class="example">
+   <p>Here is a more full example of the substitution, where the event loop is spun from inside a
+   task that is queued from work in parallel. The version using <span>spin the event loop</span>:</p>
+
+   <ol>
+    <li>
+     <p><span>In parallel</span>:</p>
+
+     <ol>
+      <li><p>Do parallel thing 1.</p></li>
+
+      <li>
+       <p><span>Queue a task</span> on the <span class="no-backref">DOM manipulation task
+       source</span> to:</p>
+
+       <ol>
+        <li><p>Do task thing 1.</p></li>
+
+        <li><p><span>Spin the event loop</span> until awesomeness happens.</p></li>
+
+        <li><p>Do task thing 2.</p></li>
+       </ol>
+      </li>
+
+      <li><p>Do parallel thing 2.</p></li>
+     </ol>
+    </li>
+   </ol>
+
+   <p>The fully expanded version:</p>
+
+   <ol>
+    <li>
+     <p><span>In parallel</span>:</p>
+
+     <ol>
+      <li><p>Do parallel thing 1.</p></li>
+
+      <li><p>Let <var>old stack</var> be null.</p></li>
+
+      <li>
+       <p><span>Queue a task</span> on the <span class="no-backref">DOM manipulation task
+       source</span> to:</p>
+
+       <ol>
+        <li><p>Do task thing 1.</p></li>
+
+        <li><p>Set <var>old stack</var> to a copy of the <span>JavaScript execution context
+        stack</span>.</p></li>
+
+        <li><p>Empty the <span>JavaScript execution context stack</span>.</p></li>
+
+        <li><p><span>Perform a microtask checkpoint</span>.</p></li>
+       </ol>
+      </li>
+
+      <li><p>Wait until awesomeness happens.</p></li>
+
+      <li>
+       <p><span>Queue a task</span> on the <span class="no-backref">DOM manipulation task
+       source</span> to:</p>
+
+       <ol>
+        <li><p>Replace the <span>JavaScript execution context stack</span> with <var>old
+        stack</var>.</p></li>
+
+        <li><p>Do task thing 2.</p></li>
+       </ol>
+      </li>
+
+      <li><p>Do parallel thing 2.</p></li>
+     </ol>
+    </li>
+   </ol>
+  </div>
 
   <hr>