diff --git a/index.html b/index.html index 9d7cf5a..e41190f 100644 --- a/index.html +++ b/index.html @@ -216,7 +216,7 @@

Sampling and Reporting Rate

The reporting rate for a pressure observer is the rate at which it runs - the [=data delivery=] steps, and it will never exceed the [=sampling rate=]. + the [=data collection=] steps, and it will never exceed the [=sampling rate=].

The [=sampling rate=] differs from the [=requested sampling rate=] when the @@ -243,26 +243,69 @@

Sampling and Reporting Rate

Platform primitives

- The [=platform collector=] refers to a platform interface, with which the [=user agent=] interacts to - obtain the telemetry readings required by this specification. + A pressure source is an abstract, [=implementation-defined=] + interface to hardware counters or an underlying framework that provides + telemetry data about a source type + defined by {{PressureSource}}. A [=pressure source=] can make use of data + fusion with data from additional sources if that provides more precise + results.

- A [=platform collector=] can be defined by the underlying platform (e.g. in a native telemetry - framework) or by the [=user agent=], if it has a direct access to hardware counters. + The telemetry data provided by a [=pressure source=] is represented in this + specification as a pressure source sample, a [=struct=] + consisting of the following [=struct/items=]: +

- A [=platform collector=] can support telemetry for different source types of computing - devices defined by {{PressureSource}}, or there can be multiple [=platform collectors=]. + A [=pressure source=] has an associated latest sample, a [=pressure source + sample=] or null. It is initially null.

- From the implementation perspective [=platform collector=] can be treated as a software proxy for the - corresponding hardware counters. It is possible to have multiple [=platform collector=] simultaneously - interacting with the same underlying hardware if the underlying platform supports it. + A platform collector is an abstract interface responsible for + obtaining telemetry samples from a [=pressure source=], transforming them + into [=pressure states=] and providing them to the [=user agent=].

- In simple cases, a [=platform collector=] represents individual hardware counters, but if the provided - counter readings are a product of data fusion performed in software, the [=platform collector=] - represents the results of the data fusion process. This may happen in user space or in kernel space. + A [=platform collector=] has the following associated data: +

+ +

+ The format of the telemetry data provided by a [=pressure source=] + and stored in its [=pressure source/latest sample=]'s [=pressure source + sample/data=] is [=implementation-defined=], and so is the process through + which a [=platform collector=] transforms it into a [=pressure state=]. +

+

+ For this specification's purposes, [=platform collectors=] are scoped to a + [=global object=] via the [=platform collector mapping=].

As collecting telemetry data often means polling hardware counters, it is not a free operation and thus, @@ -361,7 +404,8 @@

a registered observer list per supported [=source type=], which is initially empty.
  • - a reference to an underlying platform collector as detailed in [[[#platform-primitives]]]. + a platform collector mapping, an [=ordered map=] of [=source + types=] to [=platform collectors=].
    • A registered observer consists of an observer (a {{PressureObserver}} object). @@ -606,13 +650,57 @@

    The observe() method

    Run the following steps [=in parallel=]:
    1. - If |source:PressureSource| is not a [=valid source type=], - [=queue a global task=] on the [=PressureObserver task source=] - given |relevantGlobal| - to reject |promise| {{NotSupportedError}} and abort these steps. + Let |platformCollector| be null. +
      2. +
    2. + If |relevantGlobal|'s [=platform collector mapping=] + [=map/contains=] |source|: +
        +
      1. + Set |platformCollector| to |relevantGlobal|'s [=platform + collector mapping=][|source|]. +
        2. +
      +
      3. +
    3. + Otherwise: +
        +
      1. + Let |newCollector| be a new [=platform collector=] whose + [=platform collector/associated pressure source=] is null. +
        2. +
      2. + Let |pressureSource| be an [=implementation-defined=] + [=pressure source=] that provides telemetry data about + |source|, or null if none exists. +
        3. +
      3. + Set |newCollector|'s [=platform collector/associated pressure + source=] to |pressureSource|. +
        4. +
      4. + If |newCollector|'s [=platform collector/associated + pressure source=] is not null: +
          +
        1. + Set |platformCollector| to |newCollector|. +
          2. +
        2. + Set |relevantGlobal|'s [=platform collector + mapping=][|source|] to |platformCollector|. +
          3. +
        +
        5. +
    4. - Activate [=data delivery=] of |source| data to |relevantGlobal|. + If |platformCollector| is null, [=queue a global task=] on the + [=PressureObserver task source=] given |relevantGlobal| to reject + |promise| {{NotSupportedError}} and abort these steps. +
      5. +
    5. + Invoke [=activate data collection=] with |source| and + |relevantGlobal|.
    6. [=Queue a global task=] on the [=PressureObserver task source=] given @@ -623,7 +711,7 @@

      The observe() method

      1. If |relevantGlobal|'s [=registered observer list=] for |source| is [=list/empty=], - deactivate [=data delivery=] of |source| data to |relevantGlobal|. + invoke [=deactivate data collection=] with |source| and |relevantGlobal|.
      2. Return. @@ -686,9 +774,13 @@

        The unobserve() method

        If |registeredObserverList| is [=list/empty=]:
        1. - Deactivate [=data delivery=] of |source| data to + Invoke [=deactivate data collection=] with |source| and |relevantGlobal|.
          2. +
        2. + [=map/Remove=] |relevantGlobal|'s [=platform collector + mapping=][|source|]. +
      @@ -730,9 +822,13 @@

      The disconnect() method

      If |registeredObserverList| is [=list/empty=]:
      1. - Deactivate [=data delivery=] of |source| data to + Invoke [=deactivate data collection=] with |source| and |relevantGlobal|.
        2. +
      2. + [=map/Remove=] |relevantGlobal|'s [=platform collector + mapping=][|source|]. +
    @@ -1109,47 +1205,111 @@

    Supporting algorithms

    -

    Data delivery

    +

    Data Collection and Delivery

    - [=Data delivery=] from a [=platform collector=] can be activate and deactivated in an - [=implementation-defined=] manner per [=source type=] and [=global object=]. + To activate data collection given a [=source type=] |source| + and |relevantGlobal|, perform the following steps:

    - +
      +
    1. + If |relevantGlobal|'s [=platform collector mapping=] does not + [=map/contain=] |source|, abort these steps. +
      2. +
    2. + Let |platformCollector| be |relevantGlobal|'s [=platform collector + mapping=][|source|]. +
      3. +
    3. + If |platformCollector|'s [=platform collector/activated=] is true, + abort these steps. +
      4. +
    4. + Set |platformCollector|'s [=platform collector/activated=] to true. +
      5. +
    5. + In an [=implementation-defined=] manner, start running the [=data + collection=] steps with |relevantGlobal|, |source|, and + |platformCollector|. + +
      6. +

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

      + To deactivate data collection given a [=source type=] |source| + and |relevantGlobal|, perform the following steps: +

      +
        +
      1. + If |relevantGlobal|'s [=platform collector mapping=] does not + [=map/contain=] |source|, abort these steps. +
        2. +
      2. + Let |platformCollector| be |relevantGlobal|'s [=platform collector + mapping=][|source|]. +
        3. +
      3. + If |platformCollector|'s [=platform collector/activated=] is false, + abort these steps. +
        4. +
      4. + In an [=implementation-defined=] manner, stop running the [=data + collection=] steps with |relevantGlobal|, |source|, and + |platformCollector|. +
        5. +
      5. + Set |platformCollector|'s [=platform collector/activated=] to false. +
        6. +
      6. + Perform any [=implementation-defined=] steps to signal to + |platformCollector|'s [=platform collector/associated pressure source=] + to stop retrieving telemetry data. +
        7. +
      +

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

      1. - Let |source:PressureSource| be the [=source type=] of the |data| sample. + Let |pressureSource| be |platformCollector|'s [=platform + collector/associated pressure source=].
      2. - Let |state:PressureState| be an [=adjusted pressure state=] given |data| and |source|. - + If |pressureSource| is null, abort these steps.
      3. - Let |timestamp| be the [=unsafe shared current time=] corresponding - to the moment when |data| was obtained from |relevantGlobal|'s - [=platform collector=]. - + Let |sample| be |pressureSource|'s [=pressure source/latest sample=].
      4. - Let |timeValue| be the [=relative high resolution time=] based on |timestamp| and - |relevantGlobal|. + If |sample| is null, abort these steps. +
        5. +
      5. + Let |state| be an [=adjusted pressure state=] calculated from + |source| and |sample|'s [=pressure source sample/data=]. + +
        6. +
      6. + [=Assert=]: |state| is not null. +
        7. +
      7. + Let |rawTimestamp| be |sample|'s [=pressure source + sample/timestamp=]. +
        8. +
      8. + Let |timeValue| be the [=relative high resolution time=] based on + |rawTimestamp| and |relevantGlobal|.
      9. [=list/For each=] |observer:PressureObserver| in |relevantGlobal|'s @@ -1313,7 +1473,12 @@

        Handling change of [=Document/fully active=] status

        [=registered observer list=] [=ordered map=]:
        1. - Deactivate [=data delivery=] of |source| to |relevantGlobal|. + Invoke [=deactivate data collection=] with |source| and + |relevantGlobal|. +
          2. +
        2. + [=map/Remove=] |relevantGlobal|'s [=platform collector + mapping=][|source|].
        10. @@ -1358,7 +1523,12 @@

        Handling changes to worker status

        [=registered observer list=] [=ordered map=]:
        1. - Deactivate [=data delivery=] of |source| to |relevantGlobal|. + Invoke [=deactivate data collection=] with |source| and + |relevantGlobal|. +
          2. +
        2. + [=map/Remove=] |relevantGlobal|'s [=platform collector + mapping=][|source|].