Skip to content

Commit 66af549

Browse files
domenicdomenic
committed
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() (whatwg/dom#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.
1 parent bb7bde0 commit 66af549

File tree

1 file changed

+77
-41
lines changed

1 file changed

+77
-41
lines changed

‎source

Lines changed: 77 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -93936,7 +93936,7 @@ import "https://example.com/foo/../module2.mjs";</code></pre>
9393693936
</ol>
9393793937
</li>
9393893938

93939-
<li>
93939+
<li id="idle-deadline-computation">
9394093940
<p>If all of the following are true
9394193941

9394293942
<ul class="brief">
@@ -96426,12 +96426,21 @@ enum <dfn enum>DOMParserSupportedType</dfn> {
9642696426

9642796427
<div w-nodev>
9642896428

96429-
<p>Objects that implement the <code>WindowOrWorkerGlobalScope</code> mixin have a <dfn
96430-
export>map of active timers</dfn>, which is a <span>map</span>, initially empty. Each
96431-
<span data-x="map key">key</span> in this map is identified by a number, which must be unique
96432-
within the list for the lifetime of the object that implements the
96433-
<code>WindowOrWorkerGlobalScope</code> mixin, and each <span data-x="map value">value</span> is a
96434-
<code>DOMHighResTimeStamp</code>, representing the expiry time for that timer.</p>
96429+
<p>Objects that implement the <code>WindowOrWorkerGlobalScope</code> mixin have a <dfn export>map
96430+
of active timers</dfn>, which is a <span>map</span>, initially empty. Each <span data-x="map
96431+
key">key</span> in this map is an identifier for a timer, and each <span data-x="map
96432+
value">value</span> is a <code>DOMHighResTimeStamp</code>, representing the expiry time for that
96433+
timer.</p>
96434+
96435+
<p class="note">For entries put in the <span>map of active timers</span> by the <span>timer
96436+
initialization steps</span>, i.e., by <code data-x="dom-setTimeout">setTimeout()</code> and <code
96437+
data-x="dom-setInterval">setInterval()</code>, the keys are numbers. For other specifications
96438+
that use the <span>wait for a timeout</span> algorithm, the identifier is a unique non-numeric
96439+
value. Only the numeric-keyed timers are affected by <code
96440+
data-x="dom-clearTimeout">clearTimeout()</code> and <code
96441+
data-x="dom-clearInterval">clearInterval()</code>, but all timers contribute to <a
96442+
href="#idle-deadline-computation">idle deadline computation</a>, and are cleared when the
96443+
relevant global is destroyed.</p>
9643596444

9643696445
<hr>
9643796446

@@ -96580,10 +96589,57 @@ enum <dfn enum>DOMParserSupportedType</dfn> {
9658096589

9658196590
<li><p>Set <var>task</var>'s <dfn>timer nesting level</dfn> to <var>nesting level</var>.</p></li>
9658296591

96592+
<li><p>Let <var>completionStep</var> be an algorithm step which <span data-x="queue a global
96593+
task">queues a global task</span> on the <dfn export>timer task source</dfn> given
96594+
<var>global</var> to run <var>task</var>.</p></li>
96595+
96596+
<li>
96597+
<p><span>Wait for a timeout</span> given <var>global</var>, "<code
96598+
data-x="">setTimeout/setInterval</code>", <var>timeout</var>, <var>completionStep</var>, and
96599+
<var>handle</var>.</p>
96600+
96601+
<p class="note">Once the task has been processed, if <var>repeat</var> is false, it is safe to
96602+
remove the entry for <var>handle</var> from the <span>map of active timers</span> (there is no
96603+
way for the entry's existence to be detected past this point, so it does not technically matter
96604+
one way or the other).</p>
96605+
</li>
96606+
96607+
<li><p>Return <var>id</var>.</p></li>
96608+
</ol>
96609+
96610+
<p class="note">Argument conversion as defined by Web IDL (for example, invoking <code
96611+
data-x="">toString()</code> methods on objects passed as the first argument) happens in the
96612+
algorithms defined in Web IDL, before this algorithm is invoked.</p>
96613+
96614+
<div class="example">
96615+
<p>So for example, the following rather silly code will result in the log containing "<code
96616+
data-x="">ONE&nbsp;TWO&nbsp;</code>":</p>
96617+
96618+
<pre><code class="js">var log = '';
96619+
function logger(s) { log += s + ' '; }
96620+
96621+
setTimeout({ toString: function () {
96622+
setTimeout("logger('ONE')", 100);
96623+
return "logger('TWO')";
96624+
} }, 100);</code></pre>
96625+
</div>
96626+
96627+
<p>To <dfn export>wait for a timeout</dfn>, given a <code>WindowOrWorkerGlobalScope</code>
96628+
<var>global</var>, a string <var>orderingIdentifier</var>, a number <var>milliseconds</var>, a
96629+
set of steps <var>completionSteps</var>, and an optional value <var>timerKey</var>:</p>
96630+
96631+
<ol>
96632+
<li><p>Assert: if <var>timerKey</var> is given, then the caller of this algorithm is the
96633+
<span>timer initialization steps</span>. (Other specifications must not pass
96634+
<var>timerKey</var>.)</p></li>
96635+
96636+
<li><p>If <var>timerKey</var> is not given, set it to a new unique non-numeric value.</p></li>
96637+
9658396638
<li><p>Let <var>startTime</var> be the <span>current high resolution time</span>.</p></li>
9658496639

9658596640
<li><p><span data-x="map set">Set</span> <var>global</var>'s <span>map of active
96586-
timers</span>[<var>id</var>] to <var>startTime</var> plus <var>timeout</var>.</p></li>
96641+
timers</span>[<var>timerKey</var>] to <var>startTime</var> plus
96642+
<var>milliseconds</var>.</p></li>
9658796643

9658896644
<li>
9658996645
<p>Run the following steps <span>in parallel</span>:</p>
@@ -96592,17 +96648,17 @@ enum <dfn enum>DOMParserSupportedType</dfn> {
9659296648
<li>
9659396649
<p>If <var>global</var> is a <code>Window</code> object, wait until <var>global</var>'s <span
9659496650
data-x="concept-document-window">associated <code>Document</code></span> has been <span>fully
96595-
active</span> for a further <var>timeout</var> milliseconds (not necessarily
96651+
active</span> for a further <var>milliseconds</var> milliseconds (not necessarily
9659696652
consecutively).</p>
9659796653

96598-
<p>Otherwise, <var>global</var> is a <code>WorkerGlobalScope</code> object; wait
96599-
until <var>timeout</var> milliseconds have passed with the worker not suspended (not
96654+
<p>Otherwise, <var>global</var> is a <code>WorkerGlobalScope</code> object; wait until
96655+
<var>milliseconds</var> milliseconds have passed with the worker not suspended (not
9660096656
necessarily consecutively).</p>
9660196657
</li>
9660296658

96603-
<li><p>Wait until any invocations of this algorithm that had the same <var>global</var>, that
96604-
started before this one, and whose <var>timeout</var> is equal to or less than this one's,
96605-
have completed.</p></li>
96659+
<li><p>Wait until any invocations of this algorithm that had the same <var>global</var> and
96660+
<var>orderingIdentifier</var>, that started before this one, and whose <var>milliseconds</var>
96661+
is equal to or less than this one's, have completed.</p></li>
9660696662

9660796663
<li>
9660896664
<p>Optionally, wait a further <span>implementation-defined</span> length of time.</p>
@@ -96614,37 +96670,17 @@ enum <dfn enum>DOMParserSupportedType</dfn> {
9661496670
associated higher power usage.</p>
9661596671
</li>
9661696672

96617-
<li>
96618-
<p><span>Queue a global task</span> on the <dfn>timer task source</dfn> given
96619-
<var>global</var> to run <var>task</var>.</p>
96620-
96621-
<p class="note">Once the task has been processed, if <var>repeat</var> is false, it is safe
96622-
to remove the entry for <var>id</var> from the <span>map of active timers</span> (there is no
96623-
way for the entry's existence to be detected past this point, so it does not technically
96624-
matter one way or the other).</p>
96625-
</li>
96673+
<li><p>Perform <var>completionSteps</var>.</p></li>
9662696674
</ol>
9662796675
</li>
96628-
96629-
<li><p>Return <var>id</var>.</p></li>
9663096676
</ol>
9663196677

96632-
<p class="note">Argument conversion as defined by Web IDL (for example, invoking <code
96633-
data-x="">toString()</code> methods on objects passed as the first argument) happens in the
96634-
algorithms defined in Web IDL, before this algorithm is invoked.</p>
96635-
96636-
<div class="example">
96637-
<p>So for example, the following rather silly code will result in the log containing "<code
96638-
data-x="">ONE&nbsp;TWO&nbsp;</code>":</p>
96639-
96640-
<pre><code class="js">var log = '';
96641-
function logger(s) { log += s + ' '; }
96642-
96643-
setTimeout({ toString: function () {
96644-
setTimeout("logger('ONE')", 100);
96645-
return "logger('TWO')";
96646-
} }, 100);</code></pre>
96647-
</div>
96678+
<p class="note"><span>Wait for a timeout</span> is meant to be used by other specifications that
96679+
want to wait on developer-supplied timeouts, in a similar manner to <code
96680+
data-x="dom-setTimeout">setTimeout()</code>. (Note, however, it does not have the nesting and
96681+
clamping behavior of <code data-x="dom-setTimeout">setTimeout()</code>.) Such specifications can
96682+
choose an <var>orderingIdentifier</var> to ensure ordering within their specification's timeouts,
96683+
while not constraining ordering with respect to other specification's timeouts.</p>
9664896684

9664996685
</div>
9665096686

0 commit comments

Comments
 (0)