Skip to content

Commit 0bdf95e

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 1522d45 commit 0bdf95e

File tree

1 file changed

+74
-40
lines changed

1 file changed

+74
-40
lines changed

‎source

Lines changed: 74 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -93943,7 +93943,7 @@ import "https://example.com/foo/../module2.mjs";</code></pre>
9394393943
</ol>
9394493944
</li>
9394593945

93946-
<li>
93946+
<li id="idle-deadline-computation">
9394793947
<p>If all of the following are true
9394893948

9394993949
<ul class="brief">
@@ -96436,11 +96436,19 @@ enum <dfn enum>DOMParserSupportedType</dfn> {
9643696436

9643796437
<p>Objects that implement the <code>WindowOrWorkerGlobalScope</code> mixin have a <dfn
9643896438
export>map of active timers</dfn>, which is a <span>map</span>, initially empty. Each
96439-
<span data-x="map key">key</span> in this map is identified by a number, which must be unique
96440-
within the list for the lifetime of the object that implements the
96441-
<code>WindowOrWorkerGlobalScope</code> mixin, and each <span data-x="map value">value</span> is a
96439+
<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
9644296440
<code>DOMHighResTimeStamp</code>, representing the expiry time for that timer.</p>
9644396441

96442+
<p class="note">For entries put in the <span>map of active timers</span> by the <span>timer
96443+
initialization steps</span>, i.e., by <code data-x="dom-setTimeout">setTimeout()</code> and <code
96444+
data-x="dom-setInterval">setInterval()</code>, the keys are numbers. For other specifications
96445+
that use the <span>wait for a timeout</span> algorithm, the identifier is a unique opaque value.
96446+
Only the numeric-keyed timers are affected by <code
96447+
data-x="dom-clearTimeout">clearTimeout()</code> and <code
96448+
data-x="dom-clearInterval">clearInterval()</code>, but all timers contribute to <a
96449+
href="#idle-deadline-computation">idle deadline computation</a>, and are cleared when the
96450+
relevant global is destroyed.</p>
96451+
9644496452
<hr>
9644596453

9644696454
<p>The <dfn method for="WindowOrWorkerGlobalScope" data-x="dom-setTimeout"><code
@@ -96594,11 +96602,57 @@ enum <dfn enum>DOMParserSupportedType</dfn> {
9659496602

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

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

96599-
<li><p><span data-x="map set">Set</span> <var>global</var>'s
96600-
<span>map of active timers</span>[<var>handle</var>] to <var>startTime</var> plus
96601-
<var>timeout</var>.</p></li>
96653+
<li><p><span data-x="map set">Set</span> <var>global</var>'s <span>map of active
96654+
timers</span>[<var>timerKey</var>] to <var>startTime</var> plus
96655+
<var>milliseconds</var>.</p></li>
9660296656

9660396657
<li>
9660496658
<p>Run the following steps <span>in parallel</span>:</p>
@@ -96607,17 +96661,17 @@ enum <dfn enum>DOMParserSupportedType</dfn> {
9660796661
<li>
9660896662
<p>If <var>global</var> is a <code>Window</code> object, wait until <var>global</var>'s <span
9660996663
data-x="concept-document-window">associated <code>Document</code></span> has been <span>fully
96610-
active</span> for a further <var>timeout</var> milliseconds (not necessarily
96664+
active</span> for a further <var>milliseconds</var> milliseconds (not necessarily
9661196665
consecutively).</p>
9661296666

96613-
<p>Otherwise, <var>global</var> is a <code>WorkerGlobalScope</code> object; wait
96614-
until <var>timeout</var> milliseconds have passed with the worker not suspended (not
96667+
<p>Otherwise, <var>global</var> is a <code>WorkerGlobalScope</code> object; wait until
96668+
<var>milliseconds</var> milliseconds have passed with the worker not suspended (not
9661596669
necessarily consecutively).</p>
9661696670
</li>
9661796671

96618-
<li><p>Wait until any invocations of this algorithm that had the same <var>global</var>, that
96619-
started before this one, and whose <var>timeout</var> is equal to or less than this one's,
96620-
have completed.</p></li>
96672+
<li><p>Wait until any invocations of this algorithm that had the same <var>global</var> and
96673+
<var>orderingIdentifier</var>, that started before this one, and whose <var>milliseconds</var>
96674+
is equal to or less than this one's, have completed.</p></li>
9662196675

9662296676
<li>
9662396677
<p>Optionally, wait a further <span>implementation-defined</span> length of time.</p>
@@ -96629,37 +96683,17 @@ enum <dfn enum>DOMParserSupportedType</dfn> {
9662996683
associated higher power usage.</p>
9663096684
</li>
9663196685

96632-
<li>
96633-
<p><span>Queue a global task</span> on the <dfn>timer task source</dfn> given
96634-
<var>global</var> to run <var>task</var>.</p>
96635-
96636-
<p class="note">Once the task has been processed, if <var>repeat</var> is false, it is safe
96637-
to remove the entry for <var>handle</var> from the <span>map of active timers</span> (there
96638-
is no way for the entry's existence to be detected past this point, so it does not
96639-
technically matter one way or the other).</p>
96640-
</li>
96686+
<li><p>Perform <var>completionSteps</var>.</p></li>
9664196687
</ol>
9664296688
</li>
96643-
96644-
<li><p>Return <var>handle</var>.</p></li>
9664596689
</ol>
9664696690

96647-
<p class="note">Argument conversion as defined by Web IDL (for example, invoking <code
96648-
data-x="">toString()</code> methods on objects passed as the first argument) happens in the
96649-
algorithms defined in Web IDL, before this algorithm is invoked.</p>
96650-
96651-
<div class="example">
96652-
<p>So for example, the following rather silly code will result in the log containing "<code
96653-
data-x="">ONE&nbsp;TWO&nbsp;</code>":</p>
96654-
96655-
<pre><code class="js">var log = '';
96656-
function logger(s) { log += s + ' '; }
96657-
96658-
setTimeout({ toString: function () {
96659-
setTimeout("logger('ONE')", 100);
96660-
return "logger('TWO')";
96661-
} }, 100);</code></pre>
96662-
</div>
96691+
<p class="note"><span>Wait for a timeout</span> is meant to be used by other specifications that
96692+
want to wait on developer-supplied timeouts, in a similar manner to <code
96693+
data-x="dom-setTimeout">setTimeout()</code>. (Note, however, it does not have the nesting and
96694+
clamping behavior of <code data-x="dom-setTimeout">setTimeout()</code>.) Such specifications can
96695+
choose an <var>orderingIdentifier</var> to ensure ordering within their specification's timeouts,
96696+
while not constraining ordering with respect to other specification's timeouts.</p>
9666396697

9666496698
</div>
9666596699

0 commit comments

Comments
 (0)