Abstract

This document defines an API that web page authors can use to cooperatively schedule background tasks such that they do not introduce delays to other high priority tasks that share the same event loop, such as input processing, animations and frame compositing. The user agent is in a better position to determine when background tasks can be run without introducing user-perceptible delays or jank in animations and input response, based on its knowledge of currently scheduled tasks, vsync deadlines, user-interaction and so on. Using this API should therefore result in more appropriate scheduling of background tasks during times when the browser would otherwise be idle.

Status of This Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.

This document was published by the Web Performance Working Group as a Proposed Recommendation. This document is intended to become a W3C Recommendation. Comments regarding this document are welcome. Please send them to public-web-perf@w3.org (subscribe, archives) with [RequestIdleCallback] at the start of your email's subject or file a bug on GitHub.

The W3C Membership and other interested parties are invited to review the document and send comments to public-web-perf@w3.org (subscribe, archives) or file a bug on GitHub through 07 November 2017. Advisory Committee Representatives should consult their WBS questionnaires. Note that substantive technical comments for this version were expected during the Candidate Recommendation review period that ended 28 February 2017.

Please see the Working Group's implementation report.

Publication as a Proposed Recommendation does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

This document is governed by the 1 March 2017 W3C Process Document.

1. Dependencies

The terms browsing context , event loop, event loop processing model, spin the event loop, fully active, tasks, task source, task queues, queue a task, microtask queue, list of active timers, setTimeout, setInterval, requestAnimationFrame and report the error are defined in [HTML52].

The terms current high resolution time and DOMHighResTimestamp are defined in [hr-time-2].

The term conforming implementation is defined in [WebIDL].

The term hidden is defined in [page-visibility].

2. Introduction

This section is non-normative.

Web pages often want to execute computation tasks on the browser's event loop which are not time-critical, but might take a significant portion of time to perform. Examples of such background tasks include recording analytics data, long running data processing operations, client-side templating and pre-rendering of content likely to become visible in the near future. These tasks must share the event loop with other time-critical operations, such as reacting to input and performing script-based animations using requestAnimationFrame. These background tasks are typically performed by scheduling a callback using setTimeout and running the background task during that callback.

A disadvantage of this approach is that the author of the script has no way to inform the user-agent as to whether a given setTimeout callback is time-critical or could be delayed until the browser is otherwise idle. In addition, the user agent isn't able to provide the callback with any information about how long it can continue to execute without delaying time-critical operations and causing jank or other user-perceptible delays. As a result, the easiest way forward is for the author is to simply call setTimeout with a very small value, and then execute the minimum possible chunk of work in the resulting callback and reschedule additional work with another call to setTimeout. This is less than optimal because there is extra overhead from having to post many small tasks on the user agent's event loop and schedule their execution. It also relies on the user-agent interleaving other time-critical work between each of these callbacks appropriately, which is difficult since the user-agent can't make accurate assumptions on how long each of these callbacks are likely to take.

The API described in this document allows script authors to request the user-agent to schedule a callback when it would otherwise be idle. The user agent provides an estimation of how long it expects to remain idle as a deadline passed to the callback. The page author can use the deadline to ensure that these background tasks don't impact latency-critical events such as animation and input response.

Here is an example of using the API to write a background task.

Example 1
<!DOCTYPE html>
<title>Scheduling background tasks using requestIdleCallback</title>
<script>
var requestId = 0;
var pointsTotal = 0;
var pointsInside = 0;

function piStep() {
  var r = 10;
  var x = Math.random()  r  2 - r;
  var y = Math.random()  r  2 - r;
  return (Math.pow(x, 2) + Math.pow(y, 2) < Math.pow(r, 2))
}
function refinePi(deadline) {
  while (deadline.timeRemaining() > 0) {
    if (piStep())
      pointsInside++;
    pointsTotal++;
  }
  currentEstimate = (4 * pointsInside / pointsTotal);
  textElement = document.getElementById("piEstimate");
  textElement.innerHTML="Pi Estimate: " + currentEstimate;
  requestId = window.requestIdleCallback(refinePi);
}
function start() {
  requestId = window.requestIdleCallback(refinePi);
}
function stop() {
  if (requestId)
    window.cancelIdleCallback(requestId);
  requestId = 0;
}
</script>
<button onclick="start()">Click me to start!</button>
<button onclick="stop()">Click me to stop!</button>
<div id="piEstimate">Not started</div>

3. Idle Periods

This section is non-normative.

After input processing, rendering and compositing for a given frame has been completed, the user agent's main thread often becomes idle until either: the next frame begins; another pending task becomes eligible to run; or user input is received. This specification provides a means to schedule execution of callbacks during this otherwise idle time via a requestIdleCallback API.

Callbacks posted via the requestIdleCallback API become eligible to run during user agent defined idle periods. When an idle callback is run it will be given a deadline which corresponds to the end of the current idle period. The decision as to what constitutes an idle period is user agent defined, however the expectation is that they occur in periods of quiescence where the browser expects to be idle.

One example of an idle period is the time between committing a given frame to the screen and starting processing on the next frame during active animations, as shown in Figure 1 Example of an inter-frame idle period . Such idle periods will occur frequently during active animations and screen updates, but will typically be very short (i.e., less than 16ms for devices with a 60Hz vsync cycle).

Example of an inter-frame idle period.

Figure 1 Example of an inter-frame idle period
Note

The web-developer should be careful to account for all work performed by operations during an idle callback. Some operations, such as resolving a promise or triggering a page layout, may cause subsequent tasks to be scheduled to run after the idle callback has finished. In such cases, the application should account for this additional work by yielding before the deadline expires to allow these operations to be performed before the next frame deadline.

Another example of an idle period is when the user agent is idle with no screen updates occurring. In such a situation the user agent may have no upcoming tasks with which it can bound the end of the idle period. In order to avoid causing user-perceptible delays in unpredictable tasks, such as processing of user input, the length of these idle periods should be capped to a maximum value of 50ms. Once an idle period is finished the user agent can schedule another idle period if it remains idle, as shown in Figure 2 Example of an idle period when there are no pending frame updates , to enable background work to continue to occur over longer idle time periods.

Example of an idle period when there are no pending frame updates.

Figure 2 Example of an idle period when there are no pending frame updates

During an idle period the user agent will run idle callbacks in FIFO order until either the idle period ends or there are no more idle callbacks eligible to be run. As such, the user agent will not necessarily run all currently posted idle callbacks within a single idle period. Any remaining idle tasks are eligible to run during the next idle period.

Note

To deliver the best performance developers are encouraged to eliminate unnecessary callbacks (e.g. requestAnimationFrame, setTimeout, and so on) that do not perform meaningful work; do not keep such callbacks firing and waiting for events to react, instead schedule them as necessary to react to events once they become available. Such pattern improves overall efficiency, and enables the user agent to schedule long idle callbacks (up to 50ms) that can be used to efficiently perform large blocks of background work.

Only idle tasks which posted before the start of the current idle period are eligible to be run during the current idle period. As a result, if an idle callback posts another callback using requestIdleCallback, this subsequent callback won't be run during the current idle period. This enables idle callbacks to re-post themselves to be run in a future idle period if they cannot complete their work by a given deadline - i.e., allowing code patterns like the following example, without causing the callback to be repeatedly executed during a too-short idle period:

Example 2
function doWork(deadline) {
  if (deadline.timeRemaining() <= 5) {
    // This will take more than 5ms so wait until we
    // get called back with a long enough deadline.
    requestIdleCallback(doWork);
    return;
  }
  // do work...
}

At the start of the next idle period newly posted idle callbacks are appended to the end of the runnable idle callback list, thus ensuring that reposting callbacks will be run round-robin style, with each callback getting a chance to be run before that of an earlier task's reposted callback.

Note

Future versions of this specification could allow other scheduling strategies. For example, schedule idle callback within the same idle period, a period that has at least X milliseconds of idle time, and so on. Current specification only supports the case for scheduling into the next idle period, at which time the callback can execute its logic, or repost itself into the next idle period.

When the user agent determines that the web page is not user visible it can throttle idle periods to reduce the power usage of the device, for example, only triggering an idle period every 10 seconds rather than continuously.

A final subtlety to note is that there is no guarantee that a user agent will have any idle CPU time available during heavy page load. As such, it is entirely acceptable that the user agent does not schedule any idle period, which would result in the idle callbacks posted via the requestIdleCallback API being postponed for a potentially unbounded amount of time. For cases where the author prefers to execute the callback within an idle period, but requires a time bound within which it can be executed, the author can provide the timeout property in the options argument to requestIdleCallback: if the specified timeout is reached before the callback is executed within an idle period, a task is queued to execute it.

Note

The maximum deadline of 50ms is derived from studies [RESPONSETIME] which show that that a response to user input within 100ms is generally perceived as instantaneous to humans. Capping idle deadlines to 50ms means that even if the user input occurs immediately after the idle task has begun, the user agent still has a remaining 50ms in which to respond to the user input without producing user perceptible lag.

4. Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words MUST, REQUIRED, SHALL, and SHOULD are to be interpreted as described in [RFC2119].

The IDL fragments in this specification MUST be interpreted as required for conforming IDL fragments.

This specification defines a single conformance class:

conforming user agent
A user agent is considered to be a conforming user agent if it satisfies all of the MUST-, REQUIRED- and SHALL-level criteria in this specification. A conforming user agent must also be a conforming implementation of the IDL fragment in section 5. Window interface extensions.

5. Window interface extensions

The partial interface in the IDL fragment below is used to expose the requestIdleCallback operation on the Window object. [HTML52]

partial interface Window {
    unsigned long requestIdleCallback(IdleRequestCallback callback,
                                      optional IdleRequestOptions options);
    void          cancelIdleCallback(unsigned long handle);
};

dictionary IdleRequestOptions {
    unsigned long timeout;
};

interface IdleDeadline {
    DOMHighResTimeStamp timeRemaining();
    readonly attribute boolean didTimeout;
};

callback IdleRequestCallback = void (IdleDeadline deadline);

Each Window has:

5.1 The requestIdleCallback method

When requestIdleCallback(callback, options) is invoked with a given IdleRequestCallback and optional IdleRequestOptions, the user agent MUST run the following steps:

  1. Let window be this Window object.
  2. Increment the window's idle callback identifier by one.
  3. Let handle be the current value of window's idle callback identifier.
  4. Let start_idle_period be true if the window's list of idle request callbacks and it's list of runnable idle callbacks are empty, otherwise false.
  5. Push callback to the end of window's list of idle request callbacks, associated with handle.
  6. If start_idle_period is true:
    1. queue a task on the queue associated with the idle-task task source, which performs the start an idle period algorithm, passing window as a parameter.
  7. Return handle and then continue running this algorithm asynchronously.
    Note

    The following steps run in parallel and queue a timer similar to setTimeout() if the optional timeout property is provided. From here, the idle and timeout callbacks are raced and cancel each other—e.g. if the idle callback is scheduled first, then it cancels the timeout callback, and vice versa.

  8. If the timeout property is present in options and has a positive value:
    1. Wait for timeout milliseconds.
    2. Wait until all invocations of this algorithm, whose timeout added to their posted time occurred before this one's, have completed.
    3. Optionally, wait a further user-agent defined length of time.
      Note

      This is intended to allow user agents to pad timeouts as needed to optimise the power usage of the device. For example, some processors have a low-power mode where the granularity of timers is reduced; on such platforms, user agents can slow timers down to fit this schedule instead of requiring the processor to use the more accurate mode with its associated higher power usage.

    4. Queue a task on the queue associated with the idle-task task source, which performs the invoke idle callback timeout algorithm, passing handle and window as arguments.
Note

requestIdleCallback only schedules a single callback, which will be executed during a single idle period. If the callback cannot complete its work before the given deadline then it should call requestIdleCallback again (which may be done from within the callback) to schedule a future callback for the continuation of its task, and exit immediately to return control back to the event loop.

5.2 The cancelIdleCallback method

The cancelIdleCallback method is used to cancel a previously made request to schedule an idle callback. When cancelIdleCallback(handle) is invoked, the user agent MUST run the following steps:

  1. Let window be this Window object.
  2. Find the entry in either the window's list of idle request callbacks or list of runnable idle callbacks that is associated with the value handle.
  3. If there is such an entry, remove it from both window's list of idle request callbacks and the list of runnable idle callbacks.
Note

cancelIdleCallback might be invoked for an entry in window's list of idle request callbacks or the list of runnable idle callbacks. In either case the entry should be removed from the list so that the callback does not run.

5.3 The IdleDeadline interface

Each IdleDeadline has an associated time which holds a DOMHighResTimeStamp representing the absolute time in milliseconds of the deadline. This MUST be populated when the IdleDeadline is created.

When the timeRemaining() method is invoked on an IdleDeadline object it MUST return the duration, as a DOMHighResTimeStamp, between the current time and the time associated with the IdleDeadline object. The value SHOULD be accurate to 5 microseconds - see "Privacy and Security" section of [HR-TIME]. This value is calculated by performing the following steps:

  1. Let now be a DOMHighResTimeStamp representing current high resolution time in milliseconds.
  2. Let deadline be the time associated with the IdleDeadline object.
  3. Let timeRemaining be deadline - now.
  4. If timeRemaining is negative, set it to 0.
  5. Return timeRemaining.

Each IdleDeadline has an associated timeout, which is initially false. The didTimeout getter MUST return timeout.

Note

The invoke idle callback timeout algorithm sets timeout to true to specify that the callback is being executed outside an idle period, due to it having exceeded the value of the IdleRequestOptions's timeout property which was passed when the callback was registered.

6. Processing

6.1 Start an idle period algorithm

The start an idle period algorithm:

  1. Let last_deadline be the last idle period deadline associated with window
  2. Let event_loop be the event loop associated with window
  3. If last_deadline is greater than the current time:
    1. Spin the event loop until the current time is greater than or equal to last_deadline.
  4. Spin the event loop until all the task queues and the microtask queue associated with event_loop are empty.
    Note

    The expectation is that the user agent will update the rendering and browsing context to reflect the current state of any outstanding updates for all fully active Document objects associated event_loop (i.e., step 7 of event loop processing model) for any browsing context the user agent intends to render. I.e., during animations all rendering updates for the current frame will be completed after this step.

  5. Optionally, wait a further user-agent defined length of time.
    Note

    This is intended to allow user agents to delay the start of idle periods as needed to optimise the power usage of the device. For example, if the Document's hidden attribute ([page-visibility]) is true then the user agent can throttle idle period generation, for example limiting the Document to one idle period every 10 seconds to optimize for power usage.

  6. Let now be the current time.
  7. Let deadline be a time in the future until which the browser expects to remain idle. The user agent SHOULD choose deadline to ensure that no time-critical tasks will be delayed even if a callback runs for the whole time period from now to deadline. As such, it should be set to the minimum of: the closest timeout in the list of active timers as set via setTimeout and setInterval; the scheduled runtime for pending animation callbacks posted via requestAnimationFrame; pending internal timeouts such as deadlines to start rendering the next frame, process audio or any other internal task the user agent deems important.
  8. If deadline - now is greater than 50ms, then cap deadline by setting it to be now + 50ms.
    Note

    The cap of 50ms in the future is to ensure responsiveness to new user input within the threshold of human perception.

  9. Let pending_list be window's list of idle request callbacks.
  10. Let run_list be window's list of runnable idle callbacks.
  11. Append all entries from pending_list into run_list preserving order.
  12. Clear pending_list.
  13. Queue a task on the queue associated with the idle-task task source, which performs the steps defined in the invoke idle callbacks algorithm with deadline and window as parameters.
  14. Save deadline as the last idle period deadline associated with window.

The task source for these tasks is the idle-task task source.

Note

The time between now and deadline is referred to as the idle period. There can only be one idle period active at a given time for any given window. The idle period can end early if the user agent determines that it is no longer idle. If so, the next idle period cannot start until after deadline.

6.2 Invoke idle callbacks algorithm

The invoke idle callbacks algorithm:

  1. If the user-agent believes it should end the idle period early due to newly scheduled high-priority work, skip to step 4.
  2. Let now be the current time.
  3. If now is less than deadline:
    1. Pop the top callback from window's list of runnable idle callbacks.
    2. Let deadlineArg be a new IdleDeadline. Set the time associated with deadlineArg to deadline and set the timeout associated with deadlineArg to false.
    3. Call callback with deadlineArg as its argument. If an uncaught runtime script error occurs, then report the error.
    4. If window's list of runnable idle callbacks is not empty, queue a task which performs the steps in the invoke idle callbacks algorithm with deadline and window as a parameters and return from this algorithm
  4. Otherwise, if either the window's list of idle request callbacks or it's list of runnable idle callbacks are not empty, queue a task which performs the steps in the start an idle period algorithm algorithm with window and as a parameter.
Note

The user agent is free to end an idle period early, even if deadline has not yet occurred, by deciding to skip from step 1 directly to step 4. For example, the user agent may decide to do this if it determines that higher priority work has become runnable.

6.3 Invoke idle callback timeout algorithm

The invoke idle callback timeout algorithm:

  1. Let callback be the result of finding the entry in window's list of idle request callbacks or the list of runnable idle callbacks that is associated with the value given by the handle argument passed to the algorithm.
  2. If callback is not undefined:
    1. Remove callback from both window's list of idle request callbacks and the list of runnable idle callbacks.
    2. Let now be the current time.
    3. Let deadlineArg be a new IdleDeadline. Set the time associated with deadlineArg to now and set the timeout associated with deadlineArg to true.
    4. Call callback with deadlineArg as its argument. If an uncaught runtime script error occurs, then report the error.

7. Privacy and Security

When an idle callback is scheduled the user agent provides an estimate of how long it expects to remain idle. This information can be used to estimate the time taken by other application tasks and related browser work within that frame. However, developers can already access this information via other means - e.g. mark beginning of the frame via requestAnimationFrame, estimate the time of the next frame, and use that information to compute "remaining time" within any callback.

To mitigate cache and statistical fingerprinting attacks, the resolution of the time estimates returned by the IdleDeadline interface should be set to the same 5 microsecond minimum as the Performance interface defined in [HR-TIME].

8. changes

This section summarises major changes since the 31 January 2017 Candidate Recommendation of Cooperative Scheduling of Background Tasks, as a guide for general review.

Full details of all changes are available from the commit log of the w3c/requestidlecallback github repository.

Changes between this Proposed Recommendation and the 31 January 2017 Candidate Recommendation

Fix didTimeout definition.
Fixed Issue 61
Change start idle period algorithm to avoid monkey patching event loop.
Fixed Issue 57
Address feedback on timeRemaining method.
Fixed Issue 56, Issue 55, Issue 54

A. Acknowledgments

The editors would like to thank the following people for contributing to this specification: Sami Kyostila, Alex Clarke, Boris Zbarsky, Marcos Caceres, Jonas Sicking, Robert O'Callahan, David Baron, Todd Reifsteck, Tobin Titus, Elliott Sprehn, Tetsuharu OHZEKI, Lon Ingram, Domenic Denicola, Philippe Le Hegaret and Anne van Kesteren .

B. References

B.1 Normative references

[HR-TIME]
High Resolution Time. Jatinder Mann. W3C. 17 December 2012. W3C Recommendation. URL: https://www.w3.org/TR/hr-time/
[HTML52]
HTML 5.2. Steve Faulkner; Arron Eicholz; Travis Leithead; Alex Danilo; Sangwhan Moon. W3C. 8 August 2017. W3C Candidate Recommendation. URL: https://www.w3.org/TR/html52/
[RESPONSETIME]
Response time in man-computer conversational transactions. Robert B. Miller.December 1968. Fall Joint Computer Conference. URL: http://yusufarslan.net/sites/yusufarslan.net/files/upload/content/Miller1968.pdf
[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
[WebIDL]
Web IDL. Cameron McCormack; Boris Zbarsky; Tobie Langel. W3C. 15 December 2016. W3C Recommendation. URL: https://www.w3.org/TR/WebIDL-1/
[hr-time-2]
High Resolution Time Level 2. Ilya Grigorik; James Simonsen; Jatinder Mann. W3C. 3 August 2017. W3C Candidate Recommendation. URL: https://www.w3.org/TR/hr-time-2/
[page-visibility]
Page Visibility (Second Edition). Jatinder Mann; Arvind Jain. W3C. 29 October 2013. W3C Recommendation. URL: https://www.w3.org/TR/page-visibility/

B.2 Informative references

[WEBIDL]
Web IDL. Cameron McCormack; Boris Zbarsky; Tobie Langel. W3C. 15 December 2016. W3C Editor's Draft. URL: https://heycam.github.io/webidl/