From 66af549bca865872f4bf399315758559f0bc5d0b Mon Sep 17 00:00:00 2001
From: Domenic Denicola <d@domenic.me>
Date: Fri, 19 Nov 2021 15:29:43 -0500
Subject: [PATCH 1/3] Editorial: expose "wait for timeout"

This factors out a new algorithm which can be used by postTask() (https://wicg.github.io/scheduling-apis/#schedule-a-posttask-task) and AbortSignal.timeout() (https://github.com/whatwg/dom/pull/1032), ensuring that they correctly contribute to idle deadline computation and in general share all the appropriate logic with setTimeout() and setInterval().

This also exports the "timer task source" term since AbortSignal.abort() will want to use that.
---
 source | 118 +++++++++++++++++++++++++++++++++++++--------------------
 1 file changed, 77 insertions(+), 41 deletions(-)

diff --git a/source b/source
index 6912026b81c..9788f7cbbf6 100644
--- a/source
+++ b/source
@@ -93936,7 +93936,7 @@ import "https://example.com/foo/../module2.mjs";</code></pre>
     </ol>
    </li>
 
-   <li>
+   <li id="idle-deadline-computation">
     <p>If all of the following are true
 
     <ul class="brief">
@@ -96426,12 +96426,21 @@ enum <dfn enum>DOMParserSupportedType</dfn> {
 
   <div w-nodev>
 
-  <p>Objects that implement the <code>WindowOrWorkerGlobalScope</code> mixin have a <dfn
-  export>map of active timers</dfn>, which is a <span>map</span>, initially empty. Each
-  <span data-x="map key">key</span> in this map is identified by a number, which must be unique
-  within the list for the lifetime of the object that implements the
-  <code>WindowOrWorkerGlobalScope</code> mixin, and each <span data-x="map value">value</span> is a
-  <code>DOMHighResTimeStamp</code>, representing the expiry time for that timer.</p>
+  <p>Objects that implement the <code>WindowOrWorkerGlobalScope</code> mixin have a <dfn export>map
+  of active timers</dfn>, which is a <span>map</span>, initially empty. Each <span data-x="map
+  key">key</span> in this map is an identifier for a timer, and each <span data-x="map
+  value">value</span> is a <code>DOMHighResTimeStamp</code>, representing the expiry time for that
+  timer.</p>
+
+  <p class="note">For entries put in the <span>map of active timers</span> by the <span>timer
+  initialization steps</span>, i.e., by <code data-x="dom-setTimeout">setTimeout()</code> and <code
+  data-x="dom-setInterval">setInterval()</code>, the keys are numbers. For other specifications
+  that use the <span>wait for a timeout</span> algorithm, the identifier is a unique non-numeric
+  value. Only the numeric-keyed timers are affected by <code
+  data-x="dom-clearTimeout">clearTimeout()</code> and <code
+  data-x="dom-clearInterval">clearInterval()</code>, but all timers contribute to <a
+  href="#idle-deadline-computation">idle deadline computation</a>, and are cleared when the
+  relevant global is destroyed.</p>
 
   <hr>
 
@@ -96580,10 +96589,57 @@ enum <dfn enum>DOMParserSupportedType</dfn> {
 
    <li><p>Set <var>task</var>'s <dfn>timer nesting level</dfn> to <var>nesting level</var>.</p></li>
 
+   <li><p>Let <var>completionStep</var> be an algorithm step which <span data-x="queue a global
+   task">queues a global task</span> on the <dfn export>timer task source</dfn> given
+   <var>global</var> to run <var>task</var>.</p></li>
+
+   <li>
+    <p><span>Wait for a timeout</span> given <var>global</var>, "<code
+    data-x="">setTimeout/setInterval</code>", <var>timeout</var>, <var>completionStep</var>, and
+    <var>handle</var>.</p>
+
+    <p class="note">Once the task has been processed, if <var>repeat</var> is false, it is safe to
+    remove the entry for <var>handle</var> from the <span>map of active timers</span> (there is no
+    way for the entry's existence to be detected past this point, so it does not technically matter
+    one way or the other).</p>
+   </li>
+
+   <li><p>Return <var>id</var>.</p></li>
+  </ol>
+
+  <p class="note">Argument conversion as defined by Web IDL (for example, invoking <code
+  data-x="">toString()</code> methods on objects passed as the first argument) happens in the
+  algorithms defined in Web IDL, before this algorithm is invoked.</p>
+
+  <div class="example">
+   <p>So for example, the following rather silly code will result in the log containing "<code
+   data-x="">ONE&nbsp;TWO&nbsp;</code>":</p>
+
+   <pre><code class="js">var log = '';
+function logger(s) { log += s + ' '; }
+
+setTimeout({ toString: function () {
+  setTimeout("logger('ONE')", 100);
+  return "logger('TWO')";
+} }, 100);</code></pre>
+  </div>
+
+  <p>To <dfn export>wait for a timeout</dfn>, given a <code>WindowOrWorkerGlobalScope</code>
+  <var>global</var>, a string <var>orderingIdentifier</var>, a number <var>milliseconds</var>, a
+  set of steps <var>completionSteps</var>, and an optional value <var>timerKey</var>:</p>
+
+  <ol>
+   <li><p>Assert: if <var>timerKey</var> is given, then the caller of this algorithm is the
+   <span>timer initialization steps</span>. (Other specifications must not pass
+   <var>timerKey</var>.)</p></li>
+
+   <li><p>If <var>timerKey</var> is not given, set it to a new unique non-numeric value.</p></li>
+
    <li><p>Let <var>startTime</var> be the <span>current high resolution time</span>.</p></li>
 
    <li><p><span data-x="map set">Set</span> <var>global</var>'s <span>map of active
-   timers</span>[<var>id</var>] to <var>startTime</var> plus <var>timeout</var>.</p></li>
+   timers</span>[<var>timerKey</var>] to <var>startTime</var> plus
+   <var>milliseconds</var>.</p></li>
 
    <li>
     <p>Run the following steps <span>in parallel</span>:</p>
@@ -96592,17 +96648,17 @@ enum <dfn enum>DOMParserSupportedType</dfn> {
      <li>
       <p>If <var>global</var> is a <code>Window</code> object, wait until <var>global</var>'s <span
       data-x="concept-document-window">associated <code>Document</code></span> has been <span>fully
-      active</span> for a further <var>timeout</var> milliseconds (not necessarily
+      active</span> for a further <var>milliseconds</var> milliseconds (not necessarily
       consecutively).</p>
 
-      <p>Otherwise, <var>global</var> is a <code>WorkerGlobalScope</code> object; wait
-      until <var>timeout</var> milliseconds have passed with the worker not suspended (not
+      <p>Otherwise, <var>global</var> is a <code>WorkerGlobalScope</code> object; wait until
+      <var>milliseconds</var> milliseconds have passed with the worker not suspended (not
       necessarily consecutively).</p>
      </li>
 
-     <li><p>Wait until any invocations of this algorithm that had the same <var>global</var>, that
-     started before this one, and whose <var>timeout</var> is equal to or less than this one's,
-     have completed.</p></li>
+     <li><p>Wait until any invocations of this algorithm that had the same <var>global</var> and
+     <var>orderingIdentifier</var>, that started before this one, and whose <var>milliseconds</var>
+     is equal to or less than this one's, have completed.</p></li>
 
      <li>
       <p>Optionally, wait a further <span>implementation-defined</span> length of time.</p>
@@ -96614,37 +96670,17 @@ enum <dfn enum>DOMParserSupportedType</dfn> {
       associated higher power usage.</p>
      </li>
 
-     <li>
-      <p><span>Queue a global task</span> on the <dfn>timer task source</dfn> given
-      <var>global</var> to run <var>task</var>.</p>
-
-      <p class="note">Once the task has been processed, if <var>repeat</var> is false, it is safe
-      to remove the entry for <var>id</var> from the <span>map of active timers</span> (there is no
-      way for the entry's existence to be detected past this point, so it does not technically
-      matter one way or the other).</p>
-     </li>
+     <li><p>Perform <var>completionSteps</var>.</p></li>
     </ol>
    </li>
-
-   <li><p>Return <var>id</var>.</p></li>
   </ol>
 
-  <p class="note">Argument conversion as defined by Web IDL (for example, invoking <code
-  data-x="">toString()</code> methods on objects passed as the first argument) happens in the
-  algorithms defined in Web IDL, before this algorithm is invoked.</p>
-
-  <div class="example">
-   <p>So for example, the following rather silly code will result in the log containing "<code
-   data-x="">ONE&nbsp;TWO&nbsp;</code>":</p>
-
-   <pre><code class="js">var log = '';
-function logger(s) { log += s + ' '; }
-
-setTimeout({ toString: function () {
-  setTimeout("logger('ONE')", 100);
-  return "logger('TWO')";
-} }, 100);</code></pre>
-  </div>
+  <p class="note"><span>Wait for a timeout</span> is meant to be used by other specifications that
+  want to wait on developer-supplied timeouts, in a similar manner to <code
+  data-x="dom-setTimeout">setTimeout()</code>. (Note, however, it does not have the nesting and
+  clamping behavior of <code data-x="dom-setTimeout">setTimeout()</code>.) Such specifications can
+  choose an <var>orderingIdentifier</var> to ensure ordering within their specification's timeouts,
+  while not constraining ordering with respect to other specification's timeouts.</p>
 
   </div>
 

From 6949e8871d243956a370fb5f28926f120257c110 Mon Sep 17 00:00:00 2001
From: Domenic Denicola <d@domenic.me>
Date: Tue, 23 Nov 2021 12:10:13 -0500
Subject: [PATCH 2/3] Review feedback; move example

---
 source | 94 +++++++++++++++++++++++++++++++---------------------------
 1 file changed, 50 insertions(+), 44 deletions(-)

diff --git a/source b/source
index 9788f7cbbf6..24c0b435c1a 100644
--- a/source
+++ b/source
@@ -96435,8 +96435,8 @@ enum <dfn enum>DOMParserSupportedType</dfn> {
   <p class="note">For entries put in the <span>map of active timers</span> by the <span>timer
   initialization steps</span>, i.e., by <code data-x="dom-setTimeout">setTimeout()</code> and <code
   data-x="dom-setInterval">setInterval()</code>, the keys are numbers. For other specifications
-  that use the <span>wait for a timeout</span> algorithm, the identifier is a unique non-numeric
-  value. Only the numeric-keyed timers are affected by <code
+  that use the <span>run steps after a timeout</span> algorithm, the identifier is a unique
+  non-numeric value. Only the numeric-keyed timers are affected by <code
   data-x="dom-clearTimeout">clearTimeout()</code> and <code
   data-x="dom-clearInterval">clearInterval()</code>, but all timers contribute to <a
   href="#idle-deadline-computation">idle deadline computation</a>, and are cleared when the
@@ -96483,8 +96483,8 @@ enum <dfn enum>DOMParserSupportedType</dfn> {
 
    <li><p>If <var>previousId</var> was given, let <var>id</var> be <var>previousId</var>;
    otherwise, let <var>id</var> be an <span>implementation-defined</span> integer that is greater
-   than zero that will identify the timeout to be set by this call in <var>global</var>'s <span>map
-   of active timers</span>.</p></li>
+   than zero and does not already <span data-x="map exists">exist</span> in <var>global</var>'s
+   <span>map of active timers</span>.</p></li>
 
    <li>
     <p>If the <span>surrounding agent</span>'s <span data-x="concept-agent-event-loop">event
@@ -96594,14 +96594,14 @@ enum <dfn enum>DOMParserSupportedType</dfn> {
    <var>global</var> to run <var>task</var>.</p></li>
 
    <li>
-    <p><span>Wait for a timeout</span> given <var>global</var>, "<code
+    <p><span>Run steps after a timeout</span> given <var>global</var>, "<code
     data-x="">setTimeout/setInterval</code>", <var>timeout</var>, <var>completionStep</var>, and
-    <var>handle</var>.</p>
+    <var>id</var>.</p>
 
     <p class="note">Once the task has been processed, if <var>repeat</var> is false, it is safe to
-    remove the entry for <var>handle</var> from the <span>map of active timers</span> (there is no
-    way for the entry's existence to be detected past this point, so it does not technically matter
-    one way or the other).</p>
+    remove the entry for <var>id</var> from the <span>map of active timers</span> (there is no way
+    for the entry's existence to be detected past this point, so it does not technically matter one
+    way or the other).</p>
    </li>
 
    <li><p>Return <var>id</var>.</p></li>
@@ -96624,7 +96624,38 @@ setTimeout({ toString: function () {
 } }, 100);</code></pre>
   </div>
 
-  <p>To <dfn export>wait for a timeout</dfn>, given a <code>WindowOrWorkerGlobalScope</code>
+  </div>
+
+  <div class="example">
+   <p>To run tasks of several milliseconds back to back without any delay, while still yielding back
+   to the browser to avoid starving the user interface (and to avoid the browser killing the script
+   for hogging the CPU), simply queue the next timer before performing work:</p>
+
+   <pre><code class="js">function doExpensiveWork() {
+  var done = false;
+  // ...
+  // this part of the function takes up to five milliseconds
+  // set done to true if we're done
+  // ...
+  return done;
+}
+
+function rescheduleWork() {
+  var id = setTimeout(rescheduleWork, 0); // preschedule next iteration
+  if (doExpensiveWork())
+    clearTimeout(id); // clear the timeout if we don't need it
+}
+
+function scheduleWork() {
+  setTimeout(rescheduleWork, 0);
+}
+
+scheduleWork(); // queues a task to do lots of work</code></pre>
+  </div>
+
+  <div w-nodev>
+
+  <p>To <dfn export>run steps after a timeout</dfn>, given a <code>WindowOrWorkerGlobalScope</code>
   <var>global</var>, a string <var>orderingIdentifier</var>, a number <var>milliseconds</var>, a
   set of steps <var>completionSteps</var>, and an optional value <var>timerKey</var>:</p>
 
@@ -96633,7 +96664,8 @@ setTimeout({ toString: function () {
    <span>timer initialization steps</span>. (Other specifications must not pass
    <var>timerKey</var>.)</p></li>
 
-   <li><p>If <var>timerKey</var> is not given, set it to a new unique non-numeric value.</p></li>
+   <li><p>If <var>timerKey</var> is not given, then set it to a new unique non-numeric
+   value.</p></li>
 
    <li><p>Let <var>startTime</var> be the <span>current high resolution time</span>.</p></li>
 
@@ -96675,40 +96707,14 @@ setTimeout({ toString: function () {
    </li>
   </ol>
 
-  <p class="note"><span>Wait for a timeout</span> is meant to be used by other specifications that
-  want to wait on developer-supplied timeouts, in a similar manner to <code
-  data-x="dom-setTimeout">setTimeout()</code>. (Note, however, it does not have the nesting and
-  clamping behavior of <code data-x="dom-setTimeout">setTimeout()</code>.) Such specifications can
-  choose an <var>orderingIdentifier</var> to ensure ordering within their specification's timeouts,
-  while not constraining ordering with respect to other specification's timeouts.</p>
-
-  </div>
-
-  <div class="example">
-   <p>To run tasks of several milliseconds back to back without any delay, while still yielding back
-   to the browser to avoid starving the user interface (and to avoid the browser killing the script
-   for hogging the CPU), simply queue the next timer before performing work:</p>
-
-   <pre><code class="js">function doExpensiveWork() {
-  var done = false;
-  // ...
-  // this part of the function takes up to five milliseconds
-  // set done to true if we're done
-  // ...
-  return done;
-}
-
-function rescheduleWork() {
-  var id = setTimeout(rescheduleWork, 0); // preschedule next iteration
-  if (doExpensiveWork())
-    clearTimeout(id); // clear the timeout if we don't need it
-}
+  <p class="note"><span>Run steps after a timeout</span> is meant to be used by other
+  specifications that want to execute developer-supplied code after a developer-supplied timeout,
+  in a similar manner to <code data-x="dom-setTimeout">setTimeout()</code>. (Note, however, it does
+  not have the nesting and clamping behavior of <code data-x="dom-setTimeout">setTimeout()</code>.)
+  Such specifications can choose an <var>orderingIdentifier</var> to ensure ordering within their
+  specification's timeouts, while not constraining ordering with respect to other specification's
+  timeouts.</p>
 
-function scheduleWork() {
-  setTimeout(rescheduleWork, 0);
-}
-
-scheduleWork(); // queues a task to do lots of work</code></pre>
   </div>
 
 

From 004080f4482df3a19a1657a5bae7d1ab260b5a6f Mon Sep 17 00:00:00 2001
From: Domenic Denicola <d@domenic.me>
Date: Tue, 23 Nov 2021 12:12:38 -0500
Subject: [PATCH 3/3] Tweaks

---
 source | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/source b/source
index 24c0b435c1a..87bf307ea2f 100644
--- a/source
+++ b/source
@@ -96426,8 +96426,8 @@ enum <dfn enum>DOMParserSupportedType</dfn> {
 
   <div w-nodev>
 
-  <p>Objects that implement the <code>WindowOrWorkerGlobalScope</code> mixin have a <dfn export>map
-  of active timers</dfn>, which is a <span>map</span>, initially empty. Each <span data-x="map
+  <p>Objects that implement the <code>WindowOrWorkerGlobalScope</code> mixin have a <dfn>map of
+  active timers</dfn>, which is a <span>map</span>, initially empty. Each <span data-x="map
   key">key</span> in this map is an identifier for a timer, and each <span data-x="map
   value">value</span> is a <code>DOMHighResTimeStamp</code>, representing the expiry time for that
   timer.</p>
@@ -96717,7 +96717,6 @@ scheduleWork(); // queues a task to do lots of work</code></pre>
 
   </div>
 
-
   <h3>Microtask queuing</h3>
 
   <dl class="domintro">