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.

WebIDL[Exposed=(DedicatedWorker,SharedWorker,Window), SecureContext]
interface PressureObserver {
  constructor(PressureUpdateCallback callback);

  Promise<undefined> observe(PressureSource source, optional PressureObserverOptions options = {});
  undefined unobserve(PressureSource source);
  undefined disconnect();
  sequence<PressureRecord> takeRecords();

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

The PressureObserver interface represents a PressureObserver.

The new PressureObserver(callback) constructor steps are:

Set this.[[Callback]] to callback.

The observe(source, options) method steps are:

Let relevantGlobal be this's relevant global object.
For each document in relevantGlobal's owning document set:
1. If document is not allowed to use the policy-controlled feature token "compute-pressure", return a promise rejected with NotAllowedError.
Issue
Permission policy does not support workers directly yet #110, so they cannot be set per individual worker, so for now we consult the policy for all owning documents. For shared workers this means that all owning documents have to have the policy enabled, which should be easy to coordinate as shared workers require same origin.
Set this.[[SampleIntervalMap]][source] to options's sampleInterval.
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. Let platformCollector be null.
2. If relevantGlobal's platform collector mapping contains source:
  1. Set platformCollector to relevantGlobal's platform collector mapping[source].
3. Otherwise:
  1. Let newCollector be a new platform collector whose associated pressure source is null.
  2. Let virtualPressureSource be the result of invoking get a virtual pressure source with source and relevantGlobal.
  3. If virtualPressureSource is not null:
    1. If virtualPressureSource's can provide samples is true:
      1. Set newCollector's associated pressure source to virtualPressureSource.
      2. Append newCollector to virtualPressureSource's connected platform collectors.
  4. Otherwise:
    1. Let realPressureSource be an implementation-defined pressure source that provides telemetry data about source, or null if none exists.
    2. Set newCollector's associated pressure source to realPressureSource.
  5. If newCollector's associated pressure source is not null:
    1. Set platformCollector to newCollector.
    2. Set relevantGlobal's platform collector mapping[source] to platformCollector.
4. If platformCollector is null, queue a global task on the PressureObserver task source given relevantGlobal to reject promise NotSupportedError and abort these steps.
5. Invoke activate data collection with source and relevantGlobal.
6. Queue a global task on the PressureObserver task source given 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, invoke deactivate data collection with source and 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.[[SampleIntervalMap]][source].
Remove this.[[LastRecordMap]][source].
Remove this.[[AfterPenaltyRecordMap]][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.
Let registeredObserverList be relevantGlobal's registered observer list for source.
Remove any registered observer from registeredObserverList whose observer is this.
If registeredObserverList is empty:
1. Invoke deactivate data collection with source and relevantGlobal.
2. Remove relevantGlobal's platform collector mapping[source].

The disconnect() method steps are:

Empty observer.[[QueuedRecords]].
Clear this.[[SampleIntervalMap]].
Clear this.[[LastRecordMap]].
Clear this.[[AfterPenaltyRecordMap]].
For each (promiseSource, pendingPromise) of this.[[PendingObservePromises]], reject pendingPromise with an AbortError.
Let relevantGlobal be this's relevant global object.
For each source → registeredObserverList of relevantGlobal's registered observer list ordered map:
1. Remove any registered observer from registeredObserverList whose observer is this.
2. If registeredObserverList is empty:
  1. Invoke deactivate data collection with source and relevantGlobal.
  2. Remove relevantGlobal's platform collector mapping[source].

Note

The takeRecords() method steps are:

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

The knownSources getter steps are:

Return user agent's supported source types in alphabetical order.

Note

WebIDL[Exposed=(DedicatedWorker,SharedWorker,Window), SecureContext]
interface PressureRecord {
  readonly attribute PressureSource source;
  readonly attribute PressureState state;
  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 [[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 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 {
  [EnforceRange] unsigned long sampleInterval = 0;
};

The sampleInterval member represents the requested sampling interval expressed in milliseconds.

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.

The reset observation window steps given the argument observer, are as follows:

set observer.[[ObservationWindow]] to an implementation-defined randomized integer value in milliseconds within an implementation-defined range.
set observer.[[MaxChangesThreshold]] to an implementation-defined randomized integer value of maximum allowed changes within the observationWindow within an implementation-defined range.
set observer.[[PenaltyDuration]] to an implementation-defined randomized integer value in milliseconds, within an implementation-defined range.
Empty the observer.[[ChangesCountMap]] map.

Run the reset observation window steps and start a timer to re-run the steps when the observer.[[ObservationWindow]] time has passed, using different randomized values.

Note

To determine the owning document set for a relevant global object relevantGlobal:

Let owningDocumentSet be an empty set.
If relevantGlobal is Window, then append relevantGlobal's associated document to owningDocumentSet.
Otherwise, for each owner in WorkerGlobalScope relevantGlobal's owner set:
1. If owner is a Document, then append owner to owningDocumentSet.
2. If owner is a WorkerGlobalScope, set owningDocumentSet to the union of owningDocumentSet and owner's owning document set.
Return owningDocumentSet.

The document has implicit focus steps given the argument document, are as follows:

If document is not fully active, return false.
Let relevantGlobal be document's relevant global object.
For each origin in initiators of active Picture-in-Picture sessions:
1. If relevantGlobal's relevant settings object's origin is same origin 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 with focusedDocument's origin, return true.
Otherwise, return false.

The may receive data steps given the argument observer are as follows:

Let relevantGlobal be observer's relevant global object.
If relevantGlobal is a Window object:
1. Return the result of running document has implicit focus with relevantGlobal's associated Document.
If relevantGlobal is a WorkerGlobalScope object:
1. Let owningDocuments be relevantGlobal's owning document set.
2. For each document in owningDocuments:
  1. If the result of running document has implicit focus with document is true, return true.
  2. Otherwise, continue.
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 sampleInterval be observer.[[SampleIntervalMap]][source].
Let timeDeltaMilliseconds = timestamp - record.[[Time]].
If timeDeltaMilliseconds ≥ sampleInterval, return true, otherwise return false.

The has change in data steps given the argument observer, source, state, 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.
Return false.

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

Increment observer.[[ChangesCountMap]][source].
Return observer.[[ChangesCountMap]][source] ≤ observer.[[MaxChangesThreshold]].

To get a virtual pressure source, given a source type source and relevantGlobal, perform the following steps. They return a virtual pressure source or null.

Let topLevelTraversable be null.
If relevantGlobal is a Window object:
1. Set topLevelTraversable to relevantGlobal's navigable's top-level traversable.
If relevantGlobal is a DedicatedWorkerGlobalScope object:
1. Let owningDocuments be relevantGlobal's owning document set.
2. If owningDocuments is empty, return null.
3. Assert: owningDocuments's size is 1.
4. Set topLevelTraversable to owningDocuments[0]'s node navigable's top-level traversable.
If topLevelTraversable is null, return null.
Let topLevelVirtualPressureSourceMapping be the topLevelTraversable's virtual pressure source mapping.
Let virtualPressureSource be null.
If topLevelVirtualPressureSourceMapping contains source:
1. Set virtualPressureSource to topLevelVirtualPressureSourceMapping[source].
Return virtualPressureSource.

To activate data collection given a source type source and relevantGlobal, perform the following steps:

If relevantGlobal's platform collector mapping does not contain source, abort these steps.
Let platformCollector be relevantGlobal's platform collector mapping[source].
If platformCollector's activated is true, abort these steps.
Set platformCollector's activated to true.
In an implementation-defined manner, start running the data collection steps with relevantGlobal, source, and platformCollector.
Note

This step givens implementations leeway to collect telemetry data via polling or by subscribing to platform- or OS-specific notifications.

To deactivate data collection given a source type source and relevantGlobal, perform the following steps:

If relevantGlobal's platform collector mapping does not contain source, abort these steps.
Let platformCollector be relevantGlobal's platform collector mapping[source].
If platformCollector's activated is false, abort these steps.
In an implementation-defined manner, stop running the data collection steps with relevantGlobal, source, and platformCollector.
Set platformCollector's activated to false.
If platformCollector's associated pressure source is a virtual pressure source:
1. Remove platformCollector from its associated pressure source's connected platform collectors.
Otherwise, perform any implementation-defined steps to signal to platformCollector's associated pressure source to stop retrieving telemetry data.

The data collection steps given relevantGlobal, source and platformCollector are as follows:

Let pressureSource be platformCollector's associated pressure source.
If pressureSource is null, abort these steps.
Let sample be pressureSource's latest sample.
If sample is null, abort these steps.
Let state be null.
If pressureSource is a virtual pressure source:
1. Set state to sample's data.
Otherwise:
1. Set state to an adjusted pressure state calculated from source and sample's data.
  Note
  
  The mapping between sample's data and pressure states 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.
Assert: state is not null.
Let rawTimestamp be sample's timestamp.
Let timeValue be the relative high resolution time based on rawTimestamp and relevantGlobal.
For each observer in relevantGlobal's registered observer list for source:
1. If running may receive data with observer returns false, continue.
2. If running passes rate test with observer, source and timeValue returns false, continue.
3. If running has change in data with observer, source and state returns false, continue.
4. Let record be a new PressureRecord object with its [[Source]] set to source, [[State]] set to state and [[Time]] set to timeValue.
5. If observer.[[AfterPenaltyRecordMap]][source] exists:
  1. Set observer.[[AfterPenaltyRecordMap]][source] to record.
  2. Continue.
6. If running passes rate obfuscation test with observer and source returns false:
  1. Set observer.[[AfterPenaltyRecordMap]][source] to record.
  2. Set observer.[[ChangesCountMap]][source] to 0.
  3. Create timer of observer.[[PenaltyDuration]] duration with the following callback:
    1. If observer.[[AfterPenaltyRecordMap]][source] exists:
      1. Let record be observer.[[AfterPenaltyRecordMap]][source].
      2. Remove observer.[[AfterPenaltyRecordMap]][source].
      3. Run queue a record with observer, source, record.
  4. Continue.
7. Run queue a record with observer, source, record.

To queue a record given the arguments observer, source, record, run these steps:

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.

This specification defines the following unloading document cleanup steps given a Document document:

Let relevantGlobal be document's relevant global object.
For each source key of relevantGlobal's registered observer list ordered map:
1. Invoke deactivate data collection with source and relevantGlobal.
2. Remove relevantGlobal's platform collector mapping[source].

Issue 275: Properly determine bfcache integration strategy

This specification previously included steps covering the case of a Document becoming fully active again (i.e. integration with Document's reactivate steps). Those steps have been removed while the intended behavior is discussed.

Note

Whenever a WorkerGlobalScope relevantGlobal's closing flag is set to true, perform the following steps:

For each source key of relevantGlobal's registered observer list ordered map:
1. Invoke deactivate data collection with source and relevantGlobal.
2. Remove relevantGlobal's platform collector mapping[source].

Note

The Working Group will list any known attack vectors, both theoretical and real-world, in this section.

It may be 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. This attack is mitigated by 11.2.1 Data minimization, 11.2.2 Rate-limiting change notifications, and 11.2.8 Same-origin restriction.

In computer security a covert channel creates a capability to transfer information between processes that are not supposed to be allowed to communicate. In modern multi-process web engines in the generic case each window or tab resides in its own process (documents that have the same origin or sites that have the same site typically share the same process). Using this API it may be possible to create a cross-site covert channel C where a site A on one tab first broadcasts to the channel C after having manipulated the state of the CPU. Next a site B (that is not same site with site A) on another tab reads the broadcasted data from the channel C by using this API to learn when the state of the CPU has changed. This process is repeated as long as the scripts run on both the sites A and B.

This attack is mitigated by 11.2.2 Rate-limiting change notifications, 11.2.3 Rate obfuscation and 11.2.6 Break calibration. Implementers are advised to consider all these mitigations for long-running scripts.

Note

The longer the scripts run the more information can be transmitted using the proposed cross-site covert channel. For example, if a user is on a video conferencing site and another long-running site that allows for more information to be transferred compared to a regular browsing scenario. On the other hand, a workload such as a video conferencing session will typically exert sustained pressure on the CPU that makes it harder to manipulate the pressure state in a predictive manner.

Targeted de-anonymization attacks constitute a critical class of threats that jeopardize a user's anonymity. These attacks allow a malicious or partially compromised website (referred to as the “malicious site”) to ascertain whether a website visitor possesses a specific public identifier, such as an email address or a social media handle.

While anonymity may be a luxury for some, for certain individuals, it is far more than that—it is a matter of survival. Consider for instance those who engage in political protests, work as journalists covering sensitive topics, etc.

As an example, an attacker can privately share a resource with the target for instance using a public resource sharing service (“victim site”), and then measure side-effects (indicating successful access) on loading the resource via side-channels. If the logged in visitor can access the embedded resource successfully, that indicates that the current visit is indeed the intended target.

Specifically, exposing reliable information about the total CPU pressure can let an attacking site understand if a target of a cross-origin navigation (e.g. an iframe or pop-up window from another site) performed a CPU-intensive operation.

Techniques such as pop-under and tab-under can be used to hide the loading from the user.

One possible attack is that the malicious website opens e.g., a popup to a resource on a victim site to which the user is logged in (e.g. a video streaming site or online document editor) pointing to a resource shared with specific users.

Assuming that loading the resource puts increased pressure on the CPU, this would create a side-channel reveals to the attacking site if the user is logged into an account with access to the resource, deanonymizing the user.

Given that modern CPUs recover quickly from high pressure, one possible mitigation strategy could be to temporarily disable readings for a few seconds after loading popup and iframe content.

Note

This section gives a high-level view into mitigation strategies applicable to this specification. The normative definitions of these mitigations are integrated into the respective algorithms of this specification. Implementers are advised to consider the TAG guidance on private browsing modes when implementing the mitigations defined in this specification.

This specification adheres to the generic data minimization principles to limit exposure of data related to low-level details of the underlying platform to the minimum required to address its high-value use cases. This includes consideration for limiting exposure of identifying information about devices.

The specific application of data minimization principles in the context of this specification are discussed in 11.2.2 Rate-limiting change notifications and 11.2.8 Same-origin restriction.

By rate-limiting the delivery of the pressure state information we remove the attacker's 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 is 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.

The specification requires implementing the rate obfuscation mitigation to keep track of the number of pressure changes over an implementation-defined sliding observation window and set a flag if an implementation-defined threshold for the number of pressure changes is exceeded. Similarly, it is also recommended for the implementation to observe any abnormal activity such as a high number of pressure state changes spanning across multiple states, and set this flag similarly.

If this flag is set, the implementation is recommended to give the pressure observer a penalty during which it will not be able to inform scripts of changes in its pressure state as it normally would. The duration of this penalty is implementation-defined and it is recommended to be randomized. When notify pressure observers resumes operation after the penalty, it only reports the latest pressure state and disregards any interim state information received from the platform collector during this penalty.

Based on implementation experience, implementers must use:

a range in between 50 and 100 changes for PressureObserver's [[MaxChangesThreshold]] internal slot.
a range in between 5000 milliseconds and 10000 milliseconds for PressureObserver's [[PenaltyDuration]] internal slot.

Note

This section is non-normative.

Based on implementation experience, implementers are advised to use:

a range in between 300000 milliseconds (5 minutes) and 600000 milliseconds (10 minutes) for PressureObserver's [[ObservationWindow]] internal slot.

Note

In a calibration process an attacker tries to manipulate the CPU so that this API would report a transition into a certain pressure state with the highest probability in response to the pressure exerted by the fabricated workload. This break calibration mitigation solution can slow down or prevent this calibration process from succeeding by slightly changing at runtime the implementation-defined low-level hardware metrics that contribute to these pressure state transitions. Even if the initial calibration would succeed, its results will be invalidated at runtime when this mitigation is running continuously. Any attempts to recalibrate will similarly be mitigated against.

Note

This section is non-normative.

Based on implementation experience, implementers are advised to apply the mitigation to a randomized time value within a range between 120000 milliseconds (2 minutes) and 240000 milliseconds (4 minutes).

Note

By default data delivery is restricted to documents served from the same-origin as an initiator of an active picture-in-picture-session, documents capturing or the document with system focus, if any.

The documents qualifying for data delivery, under the above rules, can delegate it to documents in child navigables.

The feature can be extended to third-party contexts such as iframes only by a declared policy.

Shared workers can be shared across documents, such as top level document and those associated iframes. If one of the documents in the owner set passes the above data delivery requirements, the shared worker will qualify for data delivery. This means that the embedded iframe is able to pass along the data to the embedding document.

The Compute Pressure API poses a challenge to test authors, as fully exercising interface requires physical hardware devices that respond in predictable ways.

To address this challenge this document defines a [WEBDRIVER2] extension commands that allows defining and controlling virtual pressure sources that behave like real ones and which can have particular properties and whose readings can be entirely defined by users.

A virtual pressure source is a pressure source that simulates the behavior of a real one in controlled ways. It reports pressure changes to zero or more platform collectors connected to it.

Contrary to a real pressure source, however, it reports pressure state values directly instead of implementation-defined values that must be processed into pressure states by a platform collector. In other words, a virtual pressure source's pressure source sample's data is a PressureState.

In addition to the data associated with all pressure sources (such as pressure source sample), each virtual pressure source has:

a can provide samples boolean.
a connected platform collectors set of platform collectors.

Each top-level traversable has a virtual pressure source mapping, which is an ordered map of source types to virtual pressure source.

Note

As currently specified, virtual pressure sources only have an effect on a Window or DedicatedWorkerGlobalScope when its platform collector mapping does not have an entry for the source type the virtual pressure source represents.

In other words, creating a virtual pressure source for a source type for which observe() has already been called will not affect any existing instances until either disconnect() or unobserve() has been called on them. New instances will only make use of the new virtual pressure source if observe() is called after existing observers have been disconnected.

Similarly, if a virtual pressure source is in use by one or more PressureObserver instances and it is removed, all instances must stop observation before calls to observe() attempt to connect to a real pressure source.

HTTP Method	URI Template
POST	/session/{session id}/pressuresource

This extension command creates a new virtual pressure source of a specified source type. Calls to observe() from PressureObserver instances of the same source type will cause this virtual pressure source to be used as their backing pressure source until 13.1.1.2 Delete virtual pressure source is run.

Properties of the parameters argument used by this algorithm
Parameter name	Value type	Required
type	String	yes
supported	Boolean	no

The remote end steps given session, URL variables and parameters are:

Let virtualPressureSourceType be the result of invoking get a property "type" from parameters.
If the user agent's supported source types does not contain virtualPressureSourceType, return error with WebDriver error code invalid argument.
Let topLevelTraversable be the current browsing context's top-level traversable.
Let topLevelVirtualPressureSourceMapping be the topLevelTraversable's virtual pressure source mapping.
If topLevelVirtualPressureSourceMapping contains virtualPressureSourceType, return error with WebDriver error code invalid argument.
Let supported be the result of invoking get a property with default with "supported" and true from parameters.
Let virtualPressureSource be a new virtual pressure source.
Set virtualPressureSource's can provide samples to supported.
Set topLevelVirtualPressureSourceMapping[virtualPressureSourceType] to virtualPressureSource.
Return success with data null.

HTTP Method	URI Template
DELETE	/session/{session id}/pressuresource/{type}

This extension command deletes a given virtual pressure source, meaning that, if available, data for the given source type will be delivered the regular way, by non-virtual means.

The remote end steps given session, URL variables and parameters are:

Let virtualPressureSourceType be the value of the URL variables["type"].
If the user agent's supported source types does not contain virtualPressureSourceType, return error with WebDriver error code invalid argument.
Let topLevelTraversable be the current browsing context's top-level traversable.
Let topLevelVirtualPressureSourceMapping be the topLevelTraversable's virtual pressure source mapping.
Let pressureSource be topLevelVirtualPressureSourceMapping[virtualPressureSourceType].
For each platformCollector of pressureSource's connected platform collectors:
1. Set platformCollector's associated pressure source to null.
Remove topLevelVirtualPressureSourceMapping[virtualPressureSourceType].
Return success with data null.

HTTP Method	URI Template
POST	/session/{session id}/pressuresource/{type}

This extension command allows updating the state of a virtual pressure source by pushing a new pressure source sample.

Note

Properties of the parameters argument used by this algorithm
Parameter name	Value type	Required
sample	`PressureState`	yes

The remote end steps given session, URL variables and parameters are:

Let virtualPressureSourceType be the value of the URL variables["type"].
If the user agent's supported source types does not contain virtualPressureSourceType, return error with WebDriver error code invalid argument.
Let topLevelTraversable be the current browsing context's top-level traversable.
Let topLevelVirtualPressureSourceMapping be the topLevelTraversable's virtual pressure source mapping.
If topLevelVirtualPressureSourceMapping does not contain virtualPressureSource, return error with WebDriver error code unsupported operation.
Let virtualPressureSource be topLevelVirtualPressureSourceMapping[virtualPressureSourceType].
Let sample be the result of invoking get a property "sample" from parameters.
If sample is not of type PressureState, return error with WebDriver error code invalid argument.
Set virtualPressureSource's latest sample to a new pressure source sample whose data is sample and timestamp is the unsafe shared current time.
In an implementation-defined way, make virtualPressureSource's latest sample available to virtualPressureSource's connected platform collectors.
Return success with data null.

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();

activate data collection §10.6.2
activated §4.
adjusted pressure state §9.
[[AfterPenaltyRecordMap]] internal slot for PressureObserver §7.
associated pressure source §4.
break calibration §11.2.6
[[Callback]] internal slot for PressureObserver §7.
can provide samples §13.1
change in contributing factors is substantial §9.
[[ChangesCountMap]] internal slot for PressureObserver §7.
connected platform collectors §13.1
constructor() for PressureObserver §10.2.1
Contributing factors §9.
"cpu" enum value for PressureSource §3.2
"critical" enum value for PressureState §8.
current pressure state §7.
data §4.
data collection §10.6.2
deactivate data collection §10.6.2
disconnect() method for PressureObserver §10.2.4
document has implicit focus §10.6.1
"fair" enum value for PressureState §8.
get a virtual pressure source §10.6.1
has change in data §10.6.1
knownSources attribute for PressureObserver §10.2.6
[[LastRecordMap]] internal slot for PressureObserver §7.
latest sample §4.
max queued records §7.
[[MaxChangesThreshold]] internal slot for PressureObserver §7.
may receive data §10.6.1
"nominal" enum value for PressureState §8.
notify pressure observers §10.6.5
[[ObservationWindow]] internal slot for PressureObserver §7.
observe() method for PressureObserver §10.2.2
observer §7.
owning document set §10.6.1
passes rate obfuscation test §10.6.1
passes rate test §10.6.1
[[PenaltyDuration]] internal slot for PressureObserver §7.
[[PendingObservePromises]] internal slot for PressureObserver §7.
platform collector §4.
platform collector mapping §7.
pressure observer task queued §7.
pressure source §4.
pressure source sample §4.
Pressure states §8.
PressureObserver interface §10.2
PressureObserver task source §10.6.4
PressureObserverOptions dictionary §10.4
PressureRecord interface §10.3
PressureSource enum §3.2
PressureState enum §8.
PressureUpdateCallback §10.1
processing units §3.1
queue a pressure observer task §10.6.4
queue a record §10.6.3
[[QueuedRecords]] internal slot for PressureObserver §7.
rate obfuscation §11.2.3
registered observer §7.
registered observer list §7.
reporting rate §3.3
requested sampling interval §3.3
requested sampling rate §3.3
reset observation window §10.6.1
sampleInterval member for PressureObserverOptions §10.4.1
[[SampleIntervalMap]] internal slot for PressureObserver §7.
sampling rate §3.3
"serious" enum value for PressureState §8.
source attribute for PressureRecord §10.3.1
source type §4.
[[Source]] internal slot for PressureRecord §10.3
state attribute for PressureRecord §10.3.2
[[State]] internal slot for PressureRecord §10.3
supported source types §7.
takeRecords() method for PressureObserver §10.2.5
"thermals" enum value for PressureSource §3.2
time attribute for PressureRecord §10.3.3
[[Time]] internal slot for PressureRecord §10.3
timestamp §4.
toJSON method for PressureRecord §10.3.4
unobserve() method for PressureObserver §10.2.3
user agent §15.
valid source types §3.2
virtual pressure source §13.1
virtual pressure source mapping §13.1

[DOM] defines the following:
- Document interface
- documents
- node
- node document (for Node)
[ECMASCRIPT] defines the following:
- agent (for ECMAScript)
- globalThis attribute (for globalThis)
[HR-TIME] defines the following:
- DOMHighResTimeStamp
- relative high resolution time
- unsafe current time (for monotonic clock)
- unsafe shared current time
[HTML] defines the following:
- allowed to use
- associated document
- browsing context
- child navigables
- closing (for WorkerGlobalScope)
- DedicatedWorkerGlobalScope interface
- fully active (for Document)
- global object
- iframes element
- in parallel
- navigable (for Window)
- node navigable
- origin
- owner set (for WorkerGlobalScope)
- queue a global task
- reactivate (for Document)
- relevant global object
- relevant settings object
- report the exception
- same origin
- same site
- system focus (for top-level traversable)
- task source
- time origin (for environment settings object)
- top-level browsing context
- top-level traversable
- top-level traversable (for browsing context)
- unloading document cleanup steps
- Window interface
- WorkerGlobalScope interface
[INFRA] defines the following:
- Append (for list)
- Append (for set)
- Assert
- Clear (for map)
- clone (for list)
- contain (for list)
- contains (for map)
- continue (for iteration)
- empty (for list)
- For each (for list)
- For each (for map)
- implementation-defined
- item (for list)
- items (for struct)
- keyed (for map)
- list
- ordered map
- queue
- Remove (for list)
- Remove (for map)
- set
- size (for list)
- struct
- tuples
- union (for set)
- value (for map)
[MEDIACAPTURE-STREAMS] defines the following:
- context is capturing
[PERMISSIONS-POLICY] defines the following:
- default allowlist (for policy-controlled feature)
- policy-controlled feature
[WEBDRIVER2] defines the following:
- current browsing context
- error
- error code
- extension command URI Template
- extension commands
- get a property
- get a property with default
- invalid argument
- remote end steps
- success
- unsupported operation
[WEBIDL] defines the following:
- a new promise
- a promise rejected with
- AbortError exception
- [Default] extended attribute
- default toJSON steps
- [EnforceRange] extended attribute
- [Exposed] extended attribute
- FrozenArray interface
- getter steps
- NotAllowedError exception
- NotSupportedError exception
- object type
- Promise interface
- React (for promise)
- rejected
- resolved
- [SameObject] extended attribute
- [SecureContext] extended attribute
- sequence
- this
- TypeError exception
- undefined type
- unsigned long type

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 Pressure 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 knownSources attribute

10.3 The PressureRecord interface

10.3.1 The source attribute

10.3.2 The state attribute

10.3.3 The time attribute

10.3.4 The toJSON member

10.4 The PressureObserverOptions dictionary

10.4.1 The sampleInterval member

10.5 Life-cycle and garbage collection

10.6 Processing Model

10.6.1 Supporting algorithms

10.6.2 Data Collection and 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 status

10.6.7 Handling changes to worker status

11. Security and privacy considerations

11.1 Types of privacy and security threats

11.1.1 Timing attacks

11.1.2 Cross-site covert channel

11.1.3 Targeted de-anonymization attacks

11.2 Mitigation strategies

11.2.1 Data minimization

11.2.2 Rate-limiting change notifications

11.2.3 Rate obfuscation

11.2.4 Rate obfuscation normative parameters

11.2.5 Rate obfuscation non-normative parameters

11.2.6 Break calibration

11.2.7 Break calibration parameters

11.2.8 Same-origin restriction

12. Accessibility considerations

13. Automation

13.1 Virtual Pressure Source

13.1.1 Extension Commands

13.1.1.1 Create virtual pressure source

13.1.1.2 Delete virtual pressure source

13.1.1.3 Update virtual pressure source

14. Examples

15. Conformance

A. Acknowledgments

B. Index

B.1 Terms defined by this specification

B.2 Terms defined by reference

C. IDL Index

D. References

D.1 Normative references

D.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 `knownSources` attribute

10.3 The `PressureRecord` interface

10.3.1 The `source` attribute

10.3.2 The `state` attribute

10.3.3 The `time` attribute

10.3.4 The `toJSON` member

10.4 The `PressureObserverOptions` dictionary

10.4.1 The `sampleInterval` member