Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Editorial: expose "run steps after a timeout" #7349

Merged
merged 3 commits into from
Nov 24, 2021
Merged

Editorial: expose "run steps after a timeout" #7349

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
66af549
Editorial: expose "wait for timeout"
domenic Nov 19, 2021
6949e88
Review feedback; move example
domenic Nov 23, 2021
004080f
Tweaks
domenic Nov 23, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
94 changes: 50 additions & 44 deletions source
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
domenic marked this conversation as resolved.
Show resolved Hide resolved
href="#idle-deadline-computation">idle deadline computation</a>, and are cleared when the
Expand Down Expand Up @@ -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>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This implies that a now-cleared ID can be reused, even if less than 2^31 timers have been created so far. But this is probably best left for #7358.


<li>
<p>If the <span>surrounding agent</span>'s <span data-x="concept-agent-event-loop">event
Expand Down Expand Up @@ -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>
Expand All @@ -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;
}

domenic marked this conversation as resolved.
Show resolved Hide resolved
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() {
domenic marked this conversation as resolved.
Show resolved Hide resolved
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>

Expand All @@ -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>

Expand Down Expand Up @@ -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>


Expand Down