Compute Pressure Level 1

Abstract

The Compute Pressure API provides a way for websites to react to changes in the CPU pressure of the target device, such that websites can trade off resources for an improved user experience.

The Compute Pressure API enables developers to understand the pressure of system resources such as the CPU.

WebIDLcallback PressureUpdateCallback = undefined (
  sequence<PressureRecord> changes,
  PressureObserver observer
);

This callback will be invoked when the pressure state changes.

The PressureObserver can be used to observe changes in the pressure states.

WebIDLenum PressureSource { "cpu" };

[Exposed=(DedicatedWorker,SharedWorker,Window), SecureContext]
interface PressureObserver {
  constructor(PressureUpdateCallback callback, optional PressureObserverOptions options = {});

  Promise<undefined> observe(PressureSource source);
  undefined unobserve(PressureSource source);
  undefined disconnect();
  sequence<PressureRecord> takeRecords();

  [SameObject] static readonly attribute FrozenArray<PressureSource> supportedSources;
};

The PressureObserver interface represents a PressureObserver.

The new PressureObserver(callback, options) constructor steps are:

Set this.[[Callback]] to callback.
If options["sampleRate"] is less than or equal to 0, throw a RangeError.
Set this.[[SampleRate]] to options["sampleRate"].

The observe(source) method steps are:

Let document be this's relevant settings object's associated Document.
If document is not null and is not allowed to use the policy-controlled feature token "compute-pressure", return a promise rejected with NotAllowedError.
Issue 1
Permission policy doesn't support workers yet #110
Let promise be a new promise.
Let pendingPromiseTuple be (source, promise).
Append pendingPromiseTuple to this.[[PendingObservePromises]].
React to promise:
- If promise was fulfilled or rejected, then:
  1. Remove tuple from this.[[PendingObservePromises]].
Run the following steps in parallel:
1. If source is not a supported source type, queue a global task on the PressureObserver task source given document's relevant global object relevantGlobal to reject promise NotSupportedError and abort these steps.
2. Activate data delivery of source data to relevantGlobal.
3. Queue a global task on the PressureObserver task source given document's relevant global object relevantGlobal to run these steps:
  1. If promise was rejected, run the following substeps:
    1. If relevantGlobal's registered observer list for source is empty, deactivate data delivery of source data to relevantGlobal.
    2. Return.
  2. Append a new registered observer whose observer is this to relevantGlobal's registered observer list for source.
  3. Resolve promise.
Return promise.

The unobserve(source) method steps are:

If source is not a supported source type, throw "NotSupportedError".
Remove from this.[[QueuedRecords]] all records associated with source.
Remove this.[[LastRecordMap]][source].
For each (promiseSource, pendingPromise) of this.[[PendingObservePromises]], if source is equal to promiseSource, reject pendingPromise with an AbortError.
Let relevantGlobal be this's relevant global object.
Remove any registered observer from relevantGlobal's registered observer list for source for which this is the registered observer.
If the above registered observer list is empty, deactivate data delivery of source data to relevantGlobal.

The disconnect() method steps are:

Empty observer.[[QueuedRecords]].
Clear this.[[LastRecordMap]].
For each (promiseSource, pendingPromise) of this.[[PendingObservePromises]], reject pendingPromise with an AbortError.
Let relevantGlobal be this's relevant global object.
Remove any registered observer from relevantGlobal's' registered observer list for all supported source types for which this is the observer.
If the above registered observer list is empty, deactivate data delivery of source data to relevantGlobal.

Note

The takeRecords() method steps are:

Let records be a clone of observer.[[QueuedRecords]].
Empty observer.[[QueuedRecords]].
Return records.

The supportedSources attribute is informing on the supported source type by the platform collector.

The supportedSources getter steps are:

Let sources be a list of source.
Return observer's frozen array of supported source types.

Note

WebIDL[Exposed=(DedicatedWorker,SharedWorker,Window), SecureContext]
interface PressureRecord {
  readonly attribute PressureSource source;
  readonly attribute PressureState state;
  readonly attribute FrozenArray<PressureFactor> factors;
  readonly attribute DOMHighResTimeStamp time;
  [Default] object toJSON();
};

A constructed PressureRecord object has the following internal slots:

a [[Source]] value of type PressureSource, which represents the current source type.
a [[State]] value of type PressureState, which represents the current pressure state.
a [[Factors]], which is ordered set of PressureFactor values, which represents the current contributing factors.
a [[Time]] value of type DOMHighResTimeStamp, which corresponds to the time the data was obtained from the system, relative to the time origin of the global object associated with the PressureObserver instance that generated the notification.

The source getter steps are to return its [[Source]] internal slot.

The state getter steps are to return its [[State]] internal slot.

The factors getter steps are to return its [[Factors]] internal slot.

The time getter steps are to return its [[Time]] internal slot.

When PressureRecord.toJSON is called, run Web IDL Standard's default toJSON steps.

WebIDLdictionary PressureObserverOptions {
  double sampleRate = 1.0;
};

The sampleRate member represents the requested sampling rate expressed in Hz, ie. it represents the number of samples requested to be obtained from the hardware per second. The reporting rate will never exceed the requested sampling rate.

Note

Each global object has a strong reference to registered observers in their registered observer list (one per source).

Note

This section outlines the steps the user agent must take when implementing the specification.

Note

The passes privacy test steps given the argument observer, are as follows:

Let relevantGlobal be observer's relevant global object.
If relevantGlobal is a Window object:
1. If relevantGlobal's associated document is not fully active, return false.
If relevantGlobal is a WorkerGlobalScope object:
1. If relevantGlobal's relevant worker is not a active needed worker, return false.
For each origin in initiators of active Picture-in-Picture sessions:
1. If relevantGlobal's relevant settings object's origin is same origin-domain with origin, return true.
If relevantGlobal's browsing context is capturing, return true.
Let topLevelBC be relevantGlobal's browsing context's top-level browsing context.
If topLevelBC does not have system focus, return false.
Let focusedDocument be the topLevelBC's currently focused area's node document.
If relevantGlobal's relevant settings object's origin is same origin-domain with focusedDocument's origin, return true.
Otherwise, return false.

Note

The passes rate test steps given the argument observer, source and timestamp, are as follows:

If observer.[[LastRecordMap]][source] does not exist, return true.
Let record be observer.[[LastRecordMap]][source].
Let sampleRate be observer.[[SampleRate]].
Let timeDeltaMilliseconds = timestamp - record.[[Time]].
Let intervalSeconds = 1 / sampleRate.
If (timeDeltaMilliseconds / 1000) ≥ intervalSeconds, return true, otherwise return false.

The has change in data steps given the argument observer, source, state and factors, are as follows:

If observer.[[LastRecordMap]][source] does not exist, return true.
Let record be observer.[[LastRecordMap]][source].
If record.[[State]] is not equal to state and change in contributing factors is substantial returns true, return true.
If record.[[Factors]] and factors are not supersets of each other, return true.
Return false.

Data delivery from a platform collector can be activate and deactivated in an implementation-defined manner per source type and global object.

Note

The data delivery steps that are run when an implementation-defined data sample of source type source is obtained from global object relevantGlobal's platform collector, are as follows:

Let source be the source type of the data sample.
Let state be an implementation-defined state given data and source.
Let factors be an implementation-defined ordered set given data and source, potentially empty.
Let timestamp be a timestamp representing the time the data was obtained from the relevantGlobal's platform collector.
Note
The data sample and mapping between data sample, and pressure states and contributing factors to the current state, is implementation-defined and may use many different metrics. For instance, for CPU, it might consider processor frequency and utilization, as well as thermal conditions.
For each observer in relevantGlobal's registered observer list for source:
1. If running passes privacy test with observer returns false, continue.
2. If running passes rate test with observer, source and timestamp returns false, continue.
3. If running has change in data with observer, source, state and factors returns false, continue.
4. Run queue a record with observer, source, state, factors and timestamp.

To queue a record given the arguments observer, source, state, factors and timestamp, run these steps:

Let record be a new PressureRecord object with its [[Source]] set to source, [[State]] set to state, [[Factors]] set to factors and [[Time]] set to timestamp.
If size of observer.[[QueuedRecords]] is greater than max queued records, then remove the first item.
Append record to observer.[[QueuedRecords]].
Set observer.[[LastRecordMap]][source] to record.
Queue a pressure observer task with observer's relevant global object.

The PressureObserver task source is a task source used for scheduling tasks to 10.6.5 Notify Pressure Observers.

To queue a pressure observer task given relevantGlobal as input, run these steps:

If the relevantGlobal's pressure observer task queued is true, then return.
Set the relevantGlobal's pressure observer task queued to true.
Queue a global task on PressureObserver task source with relevantGlobal to notify pressure observers.

To notify pressure observers given relevantGlobal as input, run these steps:

Set relevantGlobal's pressure observer task queued to false.
Let notifySet be a new set of all observers in relevantGlobal’s registered observer lists.
For each observer of notifySet:
1. Let records be a clone of observer.[[QueuedRecords]].
2. Empty observer.[[QueuedRecords]].
3. If records is not empty, then invoke observer.[[Callback]] with records and observer. If this throws an exception, catch it, and report the exception.

When a Document document is no longer fully active, deactivate data delivery of data of all supported source types to document's relevant global object.

When a worker with associated WorkerGlobalScope relevantGlobal is no longer an active needed workers, deactivate data delivery of data of all supported source types to relevantGlobal.

When a Document document becomes fully active, for each non-empty registered observer list associated the source type source, activate data delivery of source data to document's relevant global object.

When a worker with associated WorkerGlobalScope relevantGlobal becomes an active needed workers, for each non-empty registered observer list associated the source type source, activate data delivery of source data to document's relevant global object.

Note

When a worker with associated WorkerGlobalScope relevantGlobal, once relevantGlobal's closing flag is set to true, deactivate data delivery for all supported source types to relevantGlobal.

As one of the unloading document cleanup steps given Document document, deactivate data delivery for all supported source types to document's relevant global object.

Please consult the Security and Privacy Self-Assessment based upon the [security-privacy-questionnaire].

Exposing hardware related events related to low -level details such as exact CPU utilization or frequency increases the risk of harming the user's privacy.

To mitigate this risk, no such low level details are exposed.

The subsections below describe the processing model. At a high level, the information exposed is reduced by the following steps:

Rate-limiting - The user agent notifies the application of changes in the information it can learn. Change notifications are rate-limited.
first-party context - The feature is only available in first-party contexts by default.

We propose exposing the pressure state via rate-limited change notifications. This aims to remove the ability to observe the precise time when a value transitions between two states.

More precisely, once the pressure observer is activated, it will be called once with initial values, and then be called when the values change. The subsequent calls will be rate-limited. When the callback is called, the most recent value is reported.

The specification will recommend a rate limit of at most one call per second for the active window, and one call per 10 seconds for all other windows. We will also recommend that the call timings are jittered across origins.

These measures benefit the user's privacy, by reducing the risk of identifying a device across multiple origins. The rate-limiting also benefits the user's security, by making it difficult to use this API for timing attacks. Last, rate-limiting change callbacks places an upper bound on the performance overhead of this API.

Rate limiting can be implemented in the user agent, but it might also be possible to simply change the polling/sampling rate of the underlying hardware counters, if not accessed via a higher level framework.

It is possible to identify users across non-same origin sites if unique or very precise values can be accessed at the same time by sites not sharing origin.

If the same pressure state and timestamp is observed by two origins, that would be a good indication that the origin is used by the same user on the same machine. For this reason, the API limits reporting pressure state changes to one origin at the time.

A common way to do this, is only to report changes to the focused page, but one of the main users of this API are video conferencing sites. These sites want to make sure that the video streams and effects doesn't negatively affect the system and thus the conferencing experience - but there are two common cases where the site will usually not be focused:

The user is taking meeting notes and the site is in the background. Commonly the video stream is only visible via a picture-in-picture window.
The user is sharing an external application window such as a presentation, or sharing the whole screen, unusually with some UI indicating sharing is happening.

For this reason, the API considers these two cases to have higher priority than whether the site is focused.

This API will only be available in frames served from the same origin as the top-level frame. This requirement is necessary for preserving the privacy benefits of the API's quantizing scheme.

The same-origin requirement above implies that the API is only available in first-party contexts by default.

This section is non-normative.

Example 2: How to access observer from callback

const samples = [];

function pressureChange(records, observer) {
  for (const record of records) {
    samples.push(record.state);

    // We only want 20 samples.
    if (samples.length == 20) {
      observer.disconnect();
      return;
    }
  }
}

const observer = new PressureObserver(pressureChange);
observer.observe("cpu");

In the following example we want to lower the number of concurrent video streams when the pressure becomes critical. For the sake of simplicity we only consider this one state.

As lowering the amount of streams might not result in exiting the critical state, or at least not immediately, we use a strategy where we lower one stream at the time every 30 seconds while still in the critical state.

We accomplish this by making sure the callback is called at least once every 30 seconds, or when the state actually changes. When the state changes we reset the interval timer.

Example 3: How to adjust the number of video feeds based on CPU pressure

let timerId = -1;
function pressureChange(records) {
  // Clear timer every time we are called, either by an actual state change,
  // or when called by setTimeout (see below).
  if (timerId > 0) {
    clearTimeout(timerId);
  }

  // When entering critical state, we want to recheck every 30sec if we are
  // still in critical state and if so, further reduce our concurrent streams.
  // For this reason we create a timer for 30 seconds that will call us back
  // with the last result in there were no change.
  const lastRecordArray = [records.at(records.length - 1)];
  timerId = setTimeout(pressureChange.bind(this, lastRecordArray), 30_000);

  for (const record of records) {
    if (record.state == "critical") {
      let streamsCount = getStreamsCount();
      setStreamsCount(streamsCount--);
    }
  }
}

const observer = new PressureObserver(pressureChange);
observer.observe("cpu");

In the following example, we want to demonstrate the usage of takeRecords(), by retrieving the remaining records accumulated since the the callback was last invoked.

It is recommended to do so before disconnect(), otherwise disconnect() will clear them and they will be lost forever.

For example, we might want to measure the pressure during a benchmarking workload, and thus want pressure telemetry for the exact duration of the workload. This means disconnecting all observers immediately when the task is completed, and manually requesting any pending pressure telemetry up to this point that might not have been delivered yet as part of the event loop cycle.

Example 4: How to handle all state changes right up until disconnect

function logWorkloadStatistics(records) {
  // do something with records.
}

const observer = new PressureObserver(logWorkloadStatistics);
observer.observe("cpu");

// Read pending state change records, otherwise they will be cleared
// when we disconnect.
const records = observer.takeRecords();
logWorkloadStatistics(records);

observer.disconnect();

In the following example, we show how to tell the observer to stop watching a specific source by invoking unobserve() with source.

Note

Example 5: How to tell the observer to stop watching for state changes for a specific source

const observer = new PressureObserver(records => { // do something with records. }));

observer.observe("cpu");
observer.observe("gpu");

// Callback now gets called whenever the pressure state changes for 'cpu' or 'gpu'.

observer.unobserve("gpu");

// Callback now only gets called whenever the pressure state changes for 'cpu'.

In the following example, we show how to tell the observer to stop watching for any state changes by calling disconnect(). Calling disconnect() will stop observing all sources observed by previous observe() calls.

Additionally it will clear all pending records collected since the last callback was invoked.

Example 6: how to tell the observer to stop watching for any state changes

const observer = new PressureObserver(records => { // do something with records. });
observer.observe("cpu");
observer.observe("gpu");

// some time later...

observer.disconnect();

// records will be an empty array, because of the previous disconnect().
const records = observer.takeRecords();

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 word RECOMMENDED in this document is to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

This specification defines conformance criteria for a single product: a user agent that implements the interfaces that it contains.

This section is non-normative.

Many thanks for valuable feedback and advice from Anssi Kostiainen, Asaf Yaffe, Chen Xing, Evan Shrubsole, François Beaufort, Jan Gora, Jesse Barnes, Joshua Bell, Kamila Hasanbega, Matt Menke, Moh Haghighat, Nicolás Peña Moreno, Opal Voravootivat, Paul Jensen, Peter Djeu, Raphael Kubo da Costa, Reilly Grant, Ulan Degenbaev, Victor Miura, Wei Wang, and Zhenyao Mo

Special thanks to Amanda Zhao, Fidel Tian, Zhiliang Wang and others from the Zoom engineering team for the feedback and hands-on experiments that have helped improve this API in real-world scenarios.

WebIDLenum PressureState { "nominal", "fair", "serious", "critical" };

enum PressureFactor { "thermal", "power-supply" };

callback PressureUpdateCallback = undefined (
  sequence<PressureRecord> changes,
  PressureObserver observer
);

enum PressureSource { "cpu" };

[Exposed=(DedicatedWorker,SharedWorker,Window), SecureContext]
interface PressureObserver {
  constructor(PressureUpdateCallback callback, optional PressureObserverOptions options = {});

  Promise<undefined> observe(PressureSource source);
  undefined unobserve(PressureSource source);
  undefined disconnect();
  sequence<PressureRecord> takeRecords();

  [SameObject] static readonly attribute FrozenArray<PressureSource> supportedSources;
};

[Exposed=(DedicatedWorker,SharedWorker,Window), SecureContext]
interface PressureRecord {
  readonly attribute PressureSource source;
  readonly attribute PressureState state;
  readonly attribute FrozenArray<PressureFactor> factors;
  readonly attribute DOMHighResTimeStamp time;
  [Default] object toJSON();
};

dictionary PressureObserverOptions {
  double sampleRate = 1.0;
};

Compute Pressure Level 1

Abstract

Status of This Document

1. Introduction

2. A Note on Feature Detection

3. Concepts

3.1 Processing Units

3.2 Supported sources

3.3 Sampling and Reporting Rate

4. Platform primitives

5. User notifications

6. Policy control

7. Internal Slot Definitions

8. Pressure States

9. Contributing Factors

10. Pressure Observer

10.1 The PressureUpdateCallback callback

10.2 The PressureObserver object

10.2.1 The constructor() method

10.2.2 The observe() method

10.2.3 The unobserve() method

10.2.4 The disconnect() method

10.2.5 The takeRecords() method

10.2.6 The supportedSources attribute

10.3 The PressureRecord interface

10.3.1 The source attribute

10.3.2 The state attribute

10.3.3 The factors attribute

10.3.4 The time attribute

10.3.5 The toJSON member

10.4 The PressureObserverOptions dictionary

10.4.1 The sampleRate member

10.5 Life-cycle and garbage collection

10.6 Processing Model

10.6.1 Supporting algorithms

10.6.2 Data delivery

10.6.3 Queue a PressureRecord

10.6.4 Queue a Pressure Observer Task

10.6.5 Notify Pressure Observers

10.6.6 Handling change of fully active

10.6.7 Handle unloading document and closing of workers

10.7 Security and privacy considerations

10.7.1 Minimizing information exposure

10.7.1.1 Rate-limiting change notifications

10.7.1.2 No side-channels

10.7.1.3 First-party contexts

10.8 Examples

10.9 Conformance

10.10 Acknowledgments

10.11 IDL Index

A. References

A.1 Normative references

A.2 Informative references

10.1 The `PressureUpdateCallback` callback

10.2 The `PressureObserver` object

10.2.1 The `constructor()` method

10.2.2 The `observe()` method

10.2.3 The `unobserve()` method

10.2.4 The `disconnect()` method

10.2.5 The `takeRecords()` method

10.2.6 The `supportedSources` attribute

10.3 The `PressureRecord` interface

10.3.1 The `source` attribute

10.3.2 The `state` attribute

10.3.3 The `factors` attribute

10.3.4 The `time` attribute

10.3.5 The `toJSON` member

10.4 The `PressureObserverOptions` dictionary

10.4.1 The `sampleRate` member