Table of Contents

• 1. Introduction
• 2. Idle Periods
• 3. Conformance
• 4. Window interface extensions
• 5. Processing Model
• A. Acknowledgments
• B. References
  • B.1 Normative references
  • B.2 Informative references

3. 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, as described in the Web IDL specification. [webidl]

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 4. Window interface extensions, as described in the Web IDL specification [webidl].

4. Window interface extensions

The partial interface in the IDL fragment below is used to expose the requestIdleCallback operation on the Window object. In the definition of requestIdleCallback below, references to the Document object [dom] are to be taken to be references to the Window object's active document. [HTML5]

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

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

callback IdleRequestCallback = void (IdleDeadline deadline);

Each Document has:

• a list of idle request callbacks, which MUST be initially empty,
• a list of runnable idle callbacks, which MUST be initially empty,
• and an idle callback identifier, which is a number which MUST initially be zero.

When requestIdleCallback(callback, timeout) is invoked, the user agent MUST run the following steps:

1. Let document be the Window object's active document object. [HTML5]
2. Increment the document's idle callback identifier by one.
3. Let handle be the document's idle callback identifier's current value
4. Append callback to document's list of idle request callbacks, associated with handle.
5. Return handle and then continue running this algorithm asynchronously.
6. If timeout is not omitted and is a positive value:
   1. Wait for timeout milliseconds.
   2. Wait until any invocations of this algorithm started before this one whose timeout is equal to or less than 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 document as arguments.

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

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

When the timeRemaining() function is called on an IdleDeadline object it MUST return the amount of time remaining before the callback's deadline as a DOMHighResTimeStamp. This value is calculated by performing the following steps:

1. Let deadline be the deadline of the associated callback as a DOMHighResTimeStamp. [hr-time-2]
2. Let now be the value returned by performance.now(). [hr-time-2]
3. Let timeRemaining be deadline - now.
4. If timeRemaining is negative, set it to 0.
5. Return timeRemainng.

The didTimeout attribute on an IdleDeadline object MUST return true if the callback was invoked by the invoke idle callback timeout algorithm, and false otherwise.

5. Processing Model

Whenever the user agent assesses that a given event loop is likely to remain idle for a non-trivial amount of time, it SHOULD initiate a new idle period for the event loop.

When the user agent wishes to start an event loop's idle period, the following steps MUST be performed:

1. Let last_deadline be the last idle period deadline associated with the current event loop, or 0 if no previous deadline exists.
2. If last_deadline is greater than the current time:
   1. Wait until the current time is greater than or equal to last_deadline.
3. Let now be the current time.
4. Let deadline be a time in the future until which the browser expects to remain idle.
5. If deadline - now is greater than 50ms, then cap deadline by setting it to be now + 50ms.
6. Let docs be the list of fully active Document objects associated with the event loop in question, sorted arbitrarily.
7. For every document in docs, in any order, perform the following steps:
   1. Let doclist be document's list of idle request callbacks.
   2. Let runlist be document's list of runnable idle callbacks.
   3. Append all entries from doclist into runlist preserving order.
   4. Clear doclist.
   5. Queue a task which performs the steps defined in the invoke idle callbacks algorithm with parameters runlist and deadline.
8. Save deadline as the last idle period deadline associated with the current event loop.

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

The invoke idle callbacks algorithm:

1. Let now be the current time.
2. If now is less than deadline:
   1. Pop callback from the runlist.
   2. Let deadlineArg be an IdleDeadline constructed with the given deadline and the didTimeout attribute set to false
   3. Call callback with deadlineArg as its argument. If an uncaught runtime script error occurs, then report the error.
   4. If runlist is not empty, the user agent SHOULD queue a task which performs the steps in the invoke idle callbacks algorithm with parameters runlist and deadline.

The invoke idle callback timeout algorithm:

1. Let callback be the result of finding the entry in the document's list of idle request callbacks or the document's 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 the document's list of idle request callbacks and the document's list of runnable idle callbacks.
   2. Let now be the current time.
   3. Let deadlineArg be an IdleDeadline constructed with a deadline of now and the didTimeout attribute set to true.
   4. Call callback with deadlineArg as its argument. If an uncaught runtime script error occurs, then report the error.