From 18ed9ce5a19dd00baad7f932dfefcffd1af5121d Mon Sep 17 00:00:00 2001 From: Kenneth Rohde Christiansen Date: Thu, 18 Apr 2024 16:25:27 +0200 Subject: [PATCH 01/44] Attempt to add Automation section and WebDriver support --- index.html | 317 ++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 316 insertions(+), 1 deletion(-) diff --git a/index.html b/index.html index 63c58c8..9f487c6 100644 --- a/index.html +++ b/index.html @@ -1092,7 +1092,8 @@

Supporting algorithms

Data delivery

- [=Data delivery=] from a [=platform collector=] can be activate and deactivated in an + [=Data delivery=] from a [=platform collector=] or [=mock platform collector=] + can be activate and deactivated in an [=implementation-defined=] manner per [=source type=] and [=global object=].

+
+

+ Automation +

+

+ The Compute Pressure API pose 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. +

+

+ Virtual Pressure Source +

+

+ A virtual pressure source simulates the behavior of a real pressure source in controlled ways. + It reports pressure changes to zero or more [=platform collectors=] connected to it. +

+

+ Each [=virtual pressure source=] has: +

+

+

+ A [=virtual pressure source=] is a string that represents a pressure source of a given [=source type=]. +

+

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

+

+ A mock platform collector is a [=platform collector=] that uses data from the [=virtual pressure sources=] + in an [=implementation-defined=] manner. +

+

+ Extension Commands +

+

+ Create virtual pressure source +

+ + + + + + + + + +
+ HTTP Method + + [=extension command URI Template|URI Template=] +
+ POST + + /session/{session id}/pressuresource +
+

+ This [=extension command=] creates a new [=virtual pressure source=] of a certain + [=source type=]. Calls to {{PressureObserver/observe()}} from {{PressureObserver}} instances + of the same [=source type=] will cause this [=virtual pressure source=] to be used as their + backing pressure source until [[[#delete-virtual-pressure-source]]] is run. +

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

+ The [=remote end steps=] given |session|, |URL variables| and |parameters| are: +

+
    +
  1. + Let |virtualPressureSourceType| be the result of invoking + get a property "type" from |parameters|. +
    2. +
  2. + If |virtualPressureSourceType| is not a [=string=], return [=error=] with [=error code|WebDriver error code=] [=invalid argument=]. +
    3. +
  3. + Let |topLevelTraversable| be the current browsing + context's [=browsing context/top-level traversable=]. +
    4. +
  4. + Let |topLevelVirtualPressureSourceMapping| be the |topLevelTraversable|'s [=virtual pressure source mapping=]. +
    5. +
  5. + If |topLevelVirtualPressureSourceMapping| contains |virtualPressureSourceType|, return [=error=] with + [=error code|WebDriver error code=] [=invalid argument=]. +
    6. +
  6. + Let |virtualPressureSource| be a new [=virtual pressure source=]. +
    7. +
  7. + Set |topLevelVirtualPressureSourceMapping|[|virtualPressureSourceType|] to |virtualPressureSource|. +
    8. +
  8. + Return [=success=] with data null. +
    9. +
+

+ Delete virtual pressure source +

+ + + + + + + + + +
+ HTTP Method + + [=extension command URI Template|URI Template=] +
+ DELETE + + /session/{session id}/pressuresource/{type} +
+

+ This [=extension command=] deletes a given [=source type=] of [=virtual pressure source=] and returns + pressure source updates back to hardware. +

+

+ The [=remote end steps=] given |session|, |URL variables| and |parameters| are: +

+
    +
  1. + Let |virtualPressureSourceType| be the value of the |URL variables|["type"]. +
    2. +
  2. + Let |topLevelTraversable| be the current browsing + context's [=browsing context/top-level traversable=]. +
    3. +
  3. + Let |topLevelVirtualPressureSourceMapping| be the |topLevelTraversable|'s [=virtual pressure source mapping=]. +
    4. +
  4. + Remove |topLevelVirtualPressureSourceMapping|[|virtualPressureSourceType|] and any data associated with its + [=virtual pressure source=], including any active data delivery to the [=mock platform collector=]. +
    5. +
  5. + Return [=success=] with data null. +
    6. +
+ +

+ Update virtual pressure source +

+ + + + + + + + + +
+ HTTP Method + + [=extension command URI Template|URI Template=] +
+ POST + + /session/{session id}/pressuresource/{type} +
+

+ This [=extension command=] allows updating the state of a [=virtual pressure source=] by pushing + additional [=pending state updates=] and turning on and off reporting by setting the + [=sample update interval=]. +

+ + + + + + + + + + + + + + + + + +
+ Properties of the parameters argument used by this algorithm +
+ Parameter name + + Value type + + Required +
+ states + + Array of strings + + no +
+ sampleInterval + + Number + + no +
+

+ The [=remote end steps=] given |session|, |URL variables| and |parameters| are: +

+
    +
  1. + Let |virtualPressureSourceType| be the value of the |URL variables|["type"]. +
    2. +
  2. + If |virtualPressureSourceType| is not a [=string=], return [=error=] with [=error code|WebDriver error code=] [=invalid argument=]. +
    3. +
  3. + Let |topLevelTraversable| be the current browsing + context's [=browsing context/top-level traversable=]. +
    4. +
  4. + Let |topLevelVirtualPressureSourceMapping| be the |topLevelTraversable|'s [=virtual pressure source mapping=]. +
    5. +
  5. + If |topLevelVirtualPressureSourceMapping| does not [=map/contain=] |virtualPressureSource|, + return [=error=] with [=error code|WebDriver error code=] [=invalid argument=]. +
    6. +
  6. + Let |virtualPressureSource| be |topLevelVirtualPressureSourceMapping|[|virtualPressureSourceType|]. +
    7. +
  7. + Let |states| be the result of invoking + get a property "states" from |parameters|. +
    8. +
  8. + If |states| is undefined or is not an Array, return [=error=] with [=error code|WebDriver error code=] [=invalid argument=]. +
    9. +
  9. + For each |state| in |states|: +
      +
    1. + If |state| is not a [=string=] and a valid {{PressureState}}, return [=error=] with [=error code|WebDriver error code=] [=invalid argument=]. +
      2. +
    2. + Push |state| to |virtualPressureSource|'s [=pending state updates=]. +
      3. +
    +
    10. +
  10. + Let |sampleInterval| be the result of invoking + get a property "sampleInterval" from |parameters|. +
    11. +
  11. + If |sampleInterval| is not an Number, return [=error=] with [=error code|WebDriver error code=] [=invalid argument=]. +
    12. +
  12. + If |sampleInterval| is negative, stop updating the [=mock platform collector=]. +
    13. +
  13. + If |sampleInterval| is positive, start updating the [=mock platform collector=] each |sampleInterval| milliseconds: +
      +
    1. + Let |state| be the result of [=stack/pop|popping=] a value from [=pending state updates=]. +
      2. +
    2. + If |state| is not undefined, update the [=mock platform collector=] with the value, or else do nothing. +
      3. +
    +
    14. + +
  14. + Return [=success=] with data null. +
    15. +
+ +
+

From da611a01dafd5d9f6c24d62f17700e5bf531b84b Mon Sep 17 00:00:00 2001 From: Kenneth Rohde Christiansen Date: Thu, 18 Apr 2024 16:47:43 +0200 Subject: [PATCH 02/44] Some fixes --- index.html | 44 ++++++++++++++++++++++++++------------------ 1 file changed, 26 insertions(+), 18 deletions(-) diff --git a/index.html b/index.html index 9f487c6..701ae71 100644 --- a/index.html +++ b/index.html @@ -1634,7 +1634,7 @@

a pending state updates [=queue=] of zero or more [=pressure states=], which is initially empty.
  • - a sample update interval positive number, initially set to 0 (update immidiately). + a sample update interval positive number, initially set to -1 (don't update).

    • @@ -1879,41 +1879,49 @@

    get a property "states" from |parameters|.
  • - If |states| is undefined or is not an Array, return [=error=] with [=error code|WebDriver error code=] [=invalid argument=]. -
    • -
  • - For each |state| in |states|: + If |states| is not undefined:
    1. - If |state| is not a [=string=] and a valid {{PressureState}}, return [=error=] with [=error code|WebDriver error code=] [=invalid argument=]. + If |states| is not an Array, return [=error=] with [=error code|WebDriver error code=] [=invalid argument=].
    2. - Push |state| to |virtualPressureSource|'s [=pending state updates=]. + For each |state| in |states|: +
        +
      1. + If |state| is not a [=string=] and a valid {{PressureState}}, return [=error=] with [=error code|WebDriver error code=] [=invalid argument=]. +
        2. +
      2. + Push |state| to |virtualPressureSource|'s [=pending state updates=]. +
        3. +
    -
  • Let |sampleInterval| be the result of invoking get a property "sampleInterval" from |parameters|.
  • - If |sampleInterval| is not an Number, return [=error=] with [=error code|WebDriver error code=] [=invalid argument=]. -
    • -
  • - If |sampleInterval| is negative, stop updating the [=mock platform collector=]. -
    • -
  • - If |sampleInterval| is positive, start updating the [=mock platform collector=] each |sampleInterval| milliseconds: + If |sampleInterval| is not undefined:
    1. - Let |state| be the result of [=stack/pop|popping=] a value from [=pending state updates=]. + If |sampleInterval| is not an Number, return [=error=] with [=error code|WebDriver error code=] [=invalid argument=].
    2. - If |state| is not undefined, update the [=mock platform collector=] with the value, or else do nothing. + If |sampleInterval| is negative, stop updating the [=mock platform collector=]. +
      3. +
    3. + If |sampleInterval| is positive, start updating the [=mock platform collector=] each |sampleInterval| milliseconds: +
        +
      1. + Let |state| be the result of [=stack/pop|popping=] a value from [=pending state updates=]. +
        2. +
      2. + If |state| is not undefined, update the [=mock platform collector=] with the value, or else do nothing. +
        3. +
    • -
  • Return [=success=] with data null.
    • From ebb89c3ba6b5391c3147d816e2a676d61a87264a Mon Sep 17 00:00:00 2001 From: Kenneth Rohde Christiansen Date: Mon, 22 Apr 2024 13:20:51 +0200 Subject: [PATCH 03/44] Fixed Arnaud's comments, add support for mocking sources --- index.html | 22 +++++++++++++++++----- 1 file changed, 17 insertions(+), 5 deletions(-) diff --git a/index.html b/index.html index 701ae71..4bee79c 100644 --- a/index.html +++ b/index.html @@ -161,6 +161,10 @@

    Pressure sources

    global system thermals and the central [=processing unit=], also known as the CPU. Future levels of this specification MAY introduce additional [=source types=].

    +

    + If a [=virtual pressure source=] exists, the [=supported source types=] is equal to the + [=source types=] [=map/keys=] in the [=virtual pressure source mapping=] [=ordered map=]. + 

           enum PressureSource { "thermals", "cpu" };
    @@ -1612,7 +1616,7 @@

    Automation

    - The Compute Pressure API pose a challenge to test authors, as fully + 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 @@ -1674,7 +1678,7 @@

    - This [=extension command=] creates a new [=virtual pressure source=] of a certain + This [=extension command=] creates a new [=virtual pressure source=] of a specified [=source type=]. Calls to {{PressureObserver/observe()}} from {{PressureObserver}} instances of the same [=source type=] will cause this [=virtual pressure source=] to be used as their backing pressure source until [[[#delete-virtual-pressure-source]]] is run. @@ -1812,6 +1816,13 @@

    additional [=pending state updates=] and turning on and off reporting by setting the [=sample update interval=].

    + + + + + + + + + +
    Properties of the parameters argument used by this algorithm @@ -1869,7 +1880,8 @@

  • If |topLevelVirtualPressureSourceMapping| does not [=map/contain=] |virtualPressureSource|, - return [=error=] with [=error code|WebDriver error code=] [=invalid argument=]. + return [=error=] with [=error code|WebDriver error code=] + unsupported operation.
  • Let |virtualPressureSource| be |topLevelVirtualPressureSourceMapping|[|virtualPressureSourceType|]. @@ -1907,10 +1919,10 @@

    If |sampleInterval| is not an Number, return [=error=] with [=error code|WebDriver error code=] [=invalid argument=].

  • - If |sampleInterval| is negative, stop updating the [=mock platform collector=]. + If |sampleInterval| is < 0, stop updating the [=mock platform collector=].
  • - If |sampleInterval| is positive, start updating the [=mock platform collector=] each |sampleInterval| milliseconds: + If |sampleInterval| is ≥ 0, start updating the [=mock platform collector=] each |sampleInterval| milliseconds:
    1. Let |state| be the result of [=stack/pop|popping=] a value from [=pending state updates=]. From 109fd7811b298dc32df10bede665d20b54aa2582 Mon Sep 17 00:00:00 2001 From: Kenneth Rohde Christiansen Date: Mon, 29 Apr 2024 12:39:23 +0200 Subject: [PATCH 04/44] Resolve comments from Raphael --- index.html | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/index.html b/index.html index 4bee79c..d606861 100644 --- a/index.html +++ b/index.html @@ -1097,7 +1097,7 @@

      Supporting algorithms

      Data delivery

      [=Data delivery=] from a [=platform collector=] or [=mock platform collector=] - can be activate and deactivated in an + can be activated and deactivated in an [=implementation-defined=] manner per [=source type=] and [=global object=].

    2. - a sample update interval positive number, initially set to -1 (don't update). + a sample update interval number, initially set to -1 (don't update).

      3. From ae4875ca3b640fc60e28b47bbe2b4bbfe460eb3c Mon Sep 17 00:00:00 2001 From: Kenneth Rohde Christiansen Date: Tue, 30 Apr 2024 14:43:17 +0200 Subject: [PATCH 05/44] WIP: Get rid of mock platform collector --- index.html | 187 ++++++++++++++++++++++++++++++----------------------- 1 file changed, 106 insertions(+), 81 deletions(-) diff --git a/index.html b/index.html index d606861..e5f3b4f 100644 --- a/index.html +++ b/index.html @@ -247,19 +247,20 @@

      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. + The [=platform collector=] refers to an abstract platform interface, with which the [=user agent=] + interacts to obtain the telemetry readings required by this specification.

      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. + framework) or by the [=user agent=] itself, if it has a direct access to hardware counters.

      A [=platform collector=] can support telemetry for different source types of computing - devices defined by {{PressureSource}}, or there can be multiple [=platform collectors=]. + devices defined by {{PressureSource}}, or there can be multiple [=platform collectors=]. This is + [=implementation-defined=].

      - From the implementation perspective [=platform collector=] can be treated as a software proxy for the + From the implementation perspective it 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.

      @@ -268,6 +269,11 @@

      Sampling and Reporting Rate

      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.

      +

      + For automation purposes, a [=platform collector=] must have the ability to connect to + [=virtual pressure sources=] and user their simulated data, as already [=adjusted pressure states=] + instead of actual platform data. +

      As collecting telemetry data often means polling hardware counters, it is not a free operation and thus, it should not happen if there are no one observing the data. See [[[#life-cycle]]] for more information. @@ -616,7 +622,7 @@

      The observe() method

      to reject |promise| {{NotSupportedError}} and abort these steps.
    3. - Activate [=data delivery=] of |source| data to |relevantGlobal|. + Activate [=data delivery=] from |relevantGlobal|'s [=platform collector=] of |source| data to |relevantGlobal|.
    4. [=Queue a global task=] on the [=PressureObserver task source=] given @@ -685,7 +691,7 @@

      The unobserve() method

    5. If the above [=registered observer list=] is [=list/empty=], - deactivate [=data delivery=] of |source| data to |relevantGlobal|. + deactivate [=data delivery=] from |relevantGlobal|'s [=platform collector=] of |source| data to |relevantGlobal|.

    @@ -1096,8 +1102,7 @@

    Supporting algorithms

    Data delivery

    - [=Data delivery=] from a [=platform collector=] or [=mock platform collector=] - can be activated and deactivated in an + [=Data delivery=] from a [=platform collector=] can be activated and deactivated in an [=implementation-defined=] manner per [=source type=] and [=global object=].

    - 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: + The data delivery steps that are run when the [=global object=] |relevantGlobal|'s + [=platform collector=] has new |data| available, and are as follows:

    1. Let |source:PressureSource| be the [=source type=] of the |data| sample.
    2. - Let |state:PressureState| be an [=adjusted pressure state=] given |data| and |source|. + Let |state:PressureState| be |data| if it comes from a [=virtual pressure source=]. +
      3. +
    3. + Otherwise, let |state:PressureState| be an [=adjusted pressure state=] given |data| and |source|. +
    4. Let |timestamp:DOMHighResTimeStamp| be a timestamp representing the time the |data| was obtained from the |relevantGlobal|'s [=platform collector=]. -
    5. [=list/For each=] |observer:PressureObserver| in |relevantGlobal|'s @@ -1635,24 +1641,20 @@

      Each [=virtual pressure source=] has:
      • - a pending state updates [=queue=] of zero or more [=pressure states=], which is initially empty. + a [=source type=]. +
        • +
      • + a pending samples [=queue=] of zero or more [=pressure states=], which is initially empty.
      • - a sample update interval number, initially set to -1 (don't update). + a sample update interval positive number.

      -

      - A [=virtual pressure source=] is a string that represents a pressure source of a given [=source type=]. -

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

      -

      - A mock platform collector is a [=platform collector=] that uses data from the [=virtual pressure sources=] - in an [=implementation-defined=] manner. -

      Extension Commands

      @@ -1709,6 +1711,28 @@

      yes +

    • + sampleInterval + + Number + + yes +
    + samples + + Array of strings + + yes +

    The [=remote end steps=] given |session|, |URL variables| and |parameters| are: @@ -1721,6 +1745,31 @@

  • If |virtualPressureSourceType| is not a [=string=], return [=error=] with [=error code|WebDriver error code=] [=invalid argument=].
    • +
  • + Let |sampleInterval| be the result of invoking + get a property "sampleInterval" from |parameters|. +
    • +
  • + If |sampleInterval| is not an Number, return [=error=] with [=error code|WebDriver error code=] [=invalid argument=]. +
    • +
  • + Let |samples| be the result of invoking + get a property "samples" from |parameters|. +
    • +
  • + If |samples| is not an Array, return [=error=] with [=error code|WebDriver error code=] [=invalid argument=]. +
    • +
  • + For each |sample| in |samples|: +
      +
    1. + If |sample| is not a [=string=] and a valid {{PressureState}}, return [=error=] with [=error code|WebDriver error code=] [=invalid argument=]. +
      2. +
    2. + [=queue/Enqueue=] |sample| to |virtualPressureSource|'s [=pending samples=]. +
      3. +
    +
  • Let |topLevelTraversable| be the current browsing context's [=browsing context/top-level traversable=]. @@ -1735,6 +1784,20 @@

  • Let |virtualPressureSource| be a new [=virtual pressure source=].
    • +
  • + In an [=implementation-defined=] way connect to the [=platform collector=] and when sampling, let it + read the first item in the |virtualPressureSource|'s [=pending samples=] as the current data sample, + or else consider that there is no data available. +
    • +
  • + Let |virtualPressureSource|'s [=sample update interval=] be |sampleInterval|. +
    • +
  • + Run the following steps [=in parallel=] at the |sampleInterval| time interval: +
      + Remove |virtualPressureSource|'s [=pending samples=] first item if the queue is not empty. +
    +
  • Set |topLevelVirtualPressureSourceMapping|[|virtualPressureSourceType|] to |virtualPressureSource|.
    • @@ -1783,7 +1846,11 @@

  • Remove |topLevelVirtualPressureSourceMapping|[|virtualPressureSourceType|] and any data associated with its - [=virtual pressure source=], including any active data delivery to the [=mock platform collector=]. + [=virtual pressure source=]. +
    • +
  • + In an [=implementation-defined=] way disconnect to the [=platform collector=] and let normal + platform data delivery resume.
  • Return [=success=] with data null. @@ -1813,8 +1880,7 @@

    This [=extension command=] allows updating the state of a [=virtual pressure source=] by pushing - additional [=pending state updates=] and turning on and off reporting by setting the - [=sample update interval=]. + additional [=pending samples=].

  • - Let |states| be the result of invoking - get a property "states" from |parameters|. + Let |samples| be the result of invoking + get a property "samples" from |parameters|.
  • - If |states| is not undefined: -
      -
    1. - If |states| is not an Array, return [=error=] with [=error code|WebDriver error code=] [=invalid argument=]. -
      2. -
    2. - For each |state| in |states|: -
        -
      1. - If |state| is not a [=string=] and a valid {{PressureState}}, return [=error=] with [=error code|WebDriver error code=] [=invalid argument=]. -
        2. -
      2. - Push |state| to |virtualPressureSource|'s [=pending state updates=]. -
        3. -
      -
      3. -
    -
  • - Let |sampleInterval| be the result of invoking - get a property "sampleInterval" from |parameters|. + If |samples| is not an Array, return [=error=] with [=error code|WebDriver error code=] [=invalid argument=].
  • - If |sampleInterval| is not undefined: + For each |sample| in |samples|:
    1. - If |sampleInterval| is not an Number, return [=error=] with [=error code|WebDriver error code=] [=invalid argument=]. -
      2. -
    2. - If |sampleInterval| is < 0, stop updating the [=mock platform collector=]. + If |sample| is not a [=string=] and a valid {{PressureState}}, return [=error=] with [=error code|WebDriver error code=] [=invalid argument=].
    3. - If |sampleInterval| is ≥ 0, start updating the [=mock platform collector=] each |sampleInterval| milliseconds: -
        -
      1. - Let |state| be the result of [=stack/pop|popping=] a value from [=pending state updates=]. -
        2. -
      2. - If |state| is not undefined, update the [=mock platform collector=] with the value, or else do nothing. -
        3. -
      + [=queue/Enqueue=] |sample| to |virtualPressureSource|'s [=pending samples=].
    • From dff5fcad93a60c5f7048385d5d55932606409d10 Mon Sep 17 00:00:00 2001 From: Kenneth Rohde Christiansen Date: Wed, 1 May 2024 10:50:52 +0200 Subject: [PATCH 06/44] Redefing platform collector and let it use virtual sources - there is one platform collector per global object (GO) - a platform collector will use virtual sources for non-worker GOs - virtual sources update data at a given sample rate set when created - pressure observers collect data at their own given sample rate --- index.html | 93 +++++++++++++++++++++++++++--------------------------- 1 file changed, 46 insertions(+), 47 deletions(-) diff --git a/index.html b/index.html index e5f3b4f..1befcbd 100644 --- a/index.html +++ b/index.html @@ -220,7 +220,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 @@ -247,27 +247,18 @@

    Sampling and Reporting Rate

    Platform primitives

    - The [=platform collector=] refers to an abstract platform interface, with which the [=user agent=] - interacts to obtain the telemetry readings required by this specification. + The [=platform collector=] refers to an abstract platform interface, with which the + [=user agent=] interacts to obtain the telemetry samples required by this specification.

    - A [=platform collector=] can be defined by the underlying platform (e.g. in a native telemetry - framework) or by the [=user agent=] itself, if it has a direct access to hardware counters. -

    -

    - A [=platform collector=] can support telemetry for different source types of computing - devices defined by {{PressureSource}}, or there can be multiple [=platform collectors=]. This is - [=implementation-defined=]. + For this specification's purposes, there is one separate [=platform collector=] per + [=global object=], which can support telemetry for different source types + defined by {{PressureSource}}.

    From the implementation perspective it 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. -

    -

    - 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. + corresponding hardware counters or underlying telemetry framework, and it can make use + of data fusion with data from additional sources if that provides better results.

    For automation purposes, a [=platform collector=] must have the ability to connect to @@ -371,7 +362,7 @@

    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 as detailed in [[[#platform-primitives]]].
    • A registered observer consists of an observer (a {{PressureObserver}} object). @@ -622,7 +613,7 @@

    The observe() method

    to reject |promise| {{NotSupportedError}} and abort these steps.
  • - Activate [=data delivery=] from |relevantGlobal|'s [=platform collector=] of |source| data to |relevantGlobal|. + Activate [=data collection=] from |relevantGlobal|'s [=platform collector=] of |source| data to |relevantGlobal|.
  • [=Queue a global task=] on the [=PressureObserver task source=] given @@ -633,7 +624,7 @@

    The observe() method

    1. If |relevantGlobal|'s [=registered observer list=] for |source| is [=list/empty=], - deactivate [=data delivery=] of |source| data to |relevantGlobal|. + deactivate [=data collection=] of |source| data to |relevantGlobal|.
    2. Return. @@ -691,7 +682,7 @@

      The unobserve() method

    3. If the above [=registered observer list=] is [=list/empty=], - deactivate [=data delivery=] from |relevantGlobal|'s [=platform collector=] of |source| data to |relevantGlobal|. + deactivate [=data collection=] from |relevantGlobal|'s [=platform collector=] of |source| data to |relevantGlobal|.

    @@ -726,7 +717,7 @@

    The disconnect() method

  • If the above [=registered observer list=] is [=list/empty=], - deactivate [=data delivery=] of |source| data to |relevantGlobal|. + deactivate [=data collection=] of |source| data to |relevantGlobal|.

    • @@ -1100,24 +1091,41 @@

    Supporting algorithms

    -

    Data delivery

    +

    Data Collection and Delivery

    - [=Data delivery=] from a [=platform collector=] can be activated and deactivated in an + [=Data collection=] from a [=platform collector=] can be activated and deactivated in an [=implementation-defined=] manner per [=source type=] and [=global object=].

    - The data delivery steps that are run when the [=global object=] |relevantGlobal|'s - [=platform collector=] has new |data| available, and are as follows: + The data collection steps given |relevantGlobal| as input, is run when + the |relevantGlobal| associated [=platform collector=] needs to obtain new |data| + for a [=source type=] |source:PressureSource| and are as follows:

    1. - Let |source:PressureSource| be the [=source type=] of the |data| sample. + Let |virtualPressureSource| be null. +
      2. +
    2. + If |relevantGlobal|'s [=navigable/active document=] |document| is not null: +
        +
      1. + Let |topLevelTraversable| be |document|'s [=node navigable=]'s [=top-level traversable=]. +
        2. +
      2. + Let |topLevelVirtualPressureSourceMapping| be the |topLevelTraversable|'s [=virtual pressure source mapping=]. +
        3. +
      3. + Set |virtualPressureSource| to |topLevelVirtualPressureSourceMapping|[|source|]. +
        4. +
    3. - Let |state:PressureState| be |data| if it comes from a [=virtual pressure source=]. + If |virtualPressureSource| is not null, let |state:PressureState| and |data| + be the first item in the |virtualPressureSource|'s [=pending samples=] + or else abort these steps if there is no data available.
    4. Otherwise, let |state:PressureState| be an [=adjusted pressure state=] given |data| and |source|. @@ -1130,7 +1138,7 @@

      Data delivery

    5. Let |timestamp:DOMHighResTimeStamp| be a timestamp representing the time the |data| was - obtained from the |relevantGlobal|'s [=platform collector=]. + collected by the |relevantGlobal|'s [=platform collector=].
    6. [=list/For each=] |observer:PressureObserver| in |relevantGlobal|'s @@ -1282,25 +1290,25 @@

      Notify Pressure Observers

      Handling change of fully active

      When a {{Document}} |document| is no longer [=Document/fully active=], - deactivate [=data delivery=] of data of all [=supported source types=] to |document|'s [=relevant global object=]. + deactivate [=data collection=] 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|. + deactivate [=data collection=] of data of all [=supported source types=] to |relevantGlobal|.

      When a {{Document}} |document| becomes [=Document/fully active=], for each non-[=list/empty=] [=registered observer list=] associated the [=source type=] |source|, - activate [=data delivery=] of |source| data to |document|'s [=relevant global object=]. + activate [=data collection=] of |source| data to |document|'s [=relevant global object=].

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

    @@ -1320,11 +1328,11 @@

    Handle unloading document and closing of workers

    When a worker with associated {{WorkerGlobalScope}} |relevantGlobal|, once |relevantGlobal|'s [=WorkerGlobalScope/closing=] flag is set to true, - deactivate [=data delivery=] for all [=supported source types=] to |relevantGlobal|. + deactivate [=data collection=] 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=]. + deactivate [=data collection=] for all [=supported source types=] to |document|'s [=relevant global object=].

    @@ -1784,11 +1792,6 @@

  • Let |virtualPressureSource| be a new [=virtual pressure source=].
    • -
  • - In an [=implementation-defined=] way connect to the [=platform collector=] and when sampling, let it - read the first item in the |virtualPressureSource|'s [=pending samples=] as the current data sample, - or else consider that there is no data available. -
  • Let |virtualPressureSource|'s [=sample update interval=] be |sampleInterval|.
    • @@ -1848,10 +1851,6 @@

    Remove |topLevelVirtualPressureSourceMapping|[|virtualPressureSourceType|] and any data associated with its [=virtual pressure source=]. -
  • - In an [=implementation-defined=] way disconnect to the [=platform collector=] and let normal - platform data delivery resume. -
  • Return [=success=] with data null.
    • From c8f8afc604495ee042148b4daeb499a14910cd24 Mon Sep 17 00:00:00 2001 From: Kenneth Rohde Christiansen Date: Wed, 1 May 2024 10:57:50 +0200 Subject: [PATCH 07/44] Attempt to fix build --- index.html | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/index.html b/index.html index 1befcbd..ced4382 100644 --- a/index.html +++ b/index.html @@ -1798,7 +1798,9 @@

  • Run the following steps [=in parallel=] at the |sampleInterval| time interval:
      - Remove |virtualPressureSource|'s [=pending samples=] first item if the queue is not empty. +
    1. + Remove |virtualPressureSource|'s [=pending samples=] first item if the queue is not empty. +
  • From ba6ccbd5afbc998331fc504ec18408d04bb99f0e Mon Sep 17 00:00:00 2001 From: Kenneth Rohde Christiansen Date: Mon, 6 May 2024 15:49:08 +0200 Subject: [PATCH 08/44] More fixes from comments --- index.html | 52 ++++++++++++---------------------------------------- 1 file changed, 12 insertions(+), 40 deletions(-) diff --git a/index.html b/index.html index ced4382..1121018 100644 --- a/index.html +++ b/index.html @@ -161,10 +161,6 @@

    Pressure sources

    global system thermals and the central [=processing unit=], also known as the CPU. Future levels of this specification MAY introduce additional [=source types=].

    -

    - If a [=virtual pressure source=] exists, the [=supported source types=] is equal to the - [=source types=] [=map/keys=] in the [=virtual pressure source mapping=] [=ordered map=]. - 

           enum PressureSource { "thermals", "cpu" };
    @@ -1098,10 +1094,10 @@

    Data Collection and Delivery

    - The data collection steps given |relevantGlobal| as input, is run when + The data collection steps given |relevantGlobal| as input, are run when the |relevantGlobal| associated [=platform collector=] needs to obtain new |data| for a [=source type=] |source:PressureSource| and are as follows:

      @@ -1730,17 +1726,6 @@

      yes - - - samples - - - Array of strings - - - yes - -

      The [=remote end steps=] given |session|, |URL variables| and |parameters| are: @@ -1760,24 +1745,6 @@

    1. If |sampleInterval| is not an Number, return [=error=] with [=error code|WebDriver error code=] [=invalid argument=].
      2. -
    2. - Let |samples| be the result of invoking - get a property "samples" from |parameters|. -
      3. -
    3. - If |samples| is not an Array, return [=error=] with [=error code|WebDriver error code=] [=invalid argument=]. -
      4. -
    4. - For each |sample| in |samples|: -
        -
      1. - If |sample| is not a [=string=] and a valid {{PressureState}}, return [=error=] with [=error code|WebDriver error code=] [=invalid argument=]. -
        2. -
      2. - [=queue/Enqueue=] |sample| to |virtualPressureSource|'s [=pending samples=]. -
        3. -
      -
    5. Let |topLevelTraversable| be the current browsing context's [=browsing context/top-level traversable=]. @@ -1832,8 +1799,8 @@

      - This [=extension command=] deletes a given [=source type=] of [=virtual pressure source=] and returns - pressure source updates back to hardware. + This [=extension command=] deletes a given [=source type=] of [=virtual pressure source=], meaning that, + if available, data will be delivered the regular way, by non-virtual means.

      The [=remote end steps=] given |session|, |URL variables| and |parameters| are: @@ -1842,6 +1809,9 @@

    6. Let |virtualPressureSourceType| be the value of the |URL variables|["type"].
      7. +
    7. + If |virtualPressureSourceType| is not a [=valid source type=], return [=error=] with [=error code|WebDriver error code=] [=invalid argument=]. +
    8. Let |topLevelTraversable| be the current browsing context's [=browsing context/top-level traversable=]. @@ -1850,8 +1820,7 @@

      Let |topLevelVirtualPressureSourceMapping| be the |topLevelTraversable|'s [=virtual pressure source mapping=].

    9. - Remove |topLevelVirtualPressureSourceMapping|[|virtualPressureSourceType|] and any data associated with its - [=virtual pressure source=]. + [map/Remove] |topLevelVirtualPressureSourceMapping|[|virtualPressureSourceType|].
    10. Return [=success=] with data null. @@ -1925,7 +1894,7 @@

      Let |virtualPressureSourceType| be the value of the |URL variables|["type"].

    11. - If |virtualPressureSourceType| is not a [=string=], return [=error=] with [=error code|WebDriver error code=] [=invalid argument=]. + If |virtualPressureSourceType| is not a [=valid source type=], return [=error=] with [=error code|WebDriver error code=] [=invalid argument=].
    12. Let |topLevelTraversable| be the current browsing @@ -1955,6 +1924,9 @@

    13. If |sample| is not a [=string=] and a valid {{PressureState}}, return [=error=] with [=error code|WebDriver error code=] [=invalid argument=].
      14. +

    + For each |sample| in |samples|: +
    1. [=queue/Enqueue=] |sample| to |virtualPressureSource|'s [=pending samples=].
      2. From ebb75c8e821afdaa0e31d3163a8bd570e422ee2b Mon Sep 17 00:00:00 2001 From: Kenneth Rohde Christiansen Date: Tue, 7 May 2024 15:32:33 +0200 Subject: [PATCH 09/44] Support dedicated workers --- index.html | 23 +++++++++++++++++++---- 1 file changed, 19 insertions(+), 4 deletions(-) diff --git a/index.html b/index.html index 1121018..7fcc343 100644 --- a/index.html +++ b/index.html @@ -1105,19 +1105,34 @@

      Data Collection and Delivery

      Let |virtualPressureSource| be null.
    2. - If |relevantGlobal|'s [=navigable/active document=] |document| is not null: + If |relevantGlobal| is a {{Window}} object:
      1. - Let |topLevelTraversable| be |document|'s [=node navigable=]'s [=top-level traversable=]. + Let |topLevelTraversable| be |relevantGlobal|'s [=Window/navigable=]'s [=top-level traversable=]. +
        2. +
      +
      3. +
    3. + If |relevantGlobal| is a {{DedicatedWorkerGlobalScope}} object: +
        +
      1. + Let |owningDocuments| be |relevantGlobal|'s [=owning document set=].
      2. - Let |topLevelVirtualPressureSourceMapping| be the |topLevelTraversable|'s [=virtual pressure source mapping=]. + If |owningDocuments| is empty, abort these steps.
      3. - Set |virtualPressureSource| to |topLevelVirtualPressureSourceMapping|[|source|]. + Let |topLevelTraversable| be |owningDocuments|[0]'s [=node navigable=]'s [=top-level traversable=].
      4. +
    4. + Let |topLevelVirtualPressureSourceMapping| be the |topLevelTraversable|'s [=virtual pressure source mapping=]. +
      5. +
    5. + Set |virtualPressureSource| to |topLevelVirtualPressureSourceMapping|[|source|]. +
      6. +
    6. If |virtualPressureSource| is not null, let |state:PressureState| and |data| be the first item in the |virtualPressureSource|'s [=pending samples=] From 4521ec48123fd11784d6206e6ce3a6f950016081 Mon Sep 17 00:00:00 2001 From: Kenneth Rohde Christiansen Date: Wed, 22 May 2024 12:49:27 +0200 Subject: [PATCH 10/44] Make the automation update only set one sample --- index.html | 73 ++++++++++++++---------------------------------------- 1 file changed, 18 insertions(+), 55 deletions(-) diff --git a/index.html b/index.html index 7fcc343..4c22bf7 100644 --- a/index.html +++ b/index.html @@ -1135,8 +1135,13 @@

      Data Collection and Delivery

    7. If |virtualPressureSource| is not null, let |state:PressureState| and |data| - be the first item in the |virtualPressureSource|'s [=pending samples=] - or else abort these steps if there is no data available. + be |virtualPressureSource|'s [=pending sample=]. +
      8. +
    8. + Set |virtualPressureSource|'s [=pending sample=] to null. +
      9. +
    9. + If |data| is null, abort these steps.
    10. Otherwise, let |state:PressureState| be an [=adjusted pressure state=] given |data| and |source|. @@ -1663,10 +1668,7 @@

      a [=source type=].

    11. - a pending samples [=queue=] of zero or more [=pressure states=], which is initially empty. -
      12. -
    12. - a sample update interval positive number. + a pending sample of type {{PressureState}} or null, which is initially null.

      13. @@ -1730,17 +1732,6 @@

      yes - - - sampleInterval - - - Number - - - yes - -

      The [=remote end steps=] given |session|, |URL variables| and |parameters| are: @@ -1753,13 +1744,6 @@

    13. If |virtualPressureSourceType| is not a [=string=], return [=error=] with [=error code|WebDriver error code=] [=invalid argument=].
      14. -
    14. - Let |sampleInterval| be the result of invoking - get a property "sampleInterval" from |parameters|. -
      15. -
    15. - If |sampleInterval| is not an Number, return [=error=] with [=error code|WebDriver error code=] [=invalid argument=]. -
    16. Let |topLevelTraversable| be the current browsing context's [=browsing context/top-level traversable=]. @@ -1774,17 +1758,6 @@

    17. Let |virtualPressureSource| be a new [=virtual pressure source=].
      18. -
    18. - Let |virtualPressureSource|'s [=sample update interval=] be |sampleInterval|. -
      19. -
    19. - Run the following steps [=in parallel=] at the |sampleInterval| time interval: -
        -
      1. - Remove |virtualPressureSource|'s [=pending samples=] first item if the queue is not empty. -
        2. -
      -
    20. Set |topLevelVirtualPressureSourceMapping|[|virtualPressureSourceType|] to |virtualPressureSource|.
      21. @@ -1865,7 +1838,7 @@

      This [=extension command=] allows updating the state of a [=virtual pressure source=] by pushing - additional [=pending samples=]. + a new [=pending sample=].

    21. - Let |samples| be the result of invoking - get a property "samples" from |parameters|. + Let |sample| be the result of invoking + get a property "sample" from |parameters|.
    22. - If |samples| is not an Array, return [=error=] with [=error code|WebDriver error code=] [=invalid argument=]. + If |sample| is not of type {{PressureState}}, return [=error=] with [=error code|WebDriver error code=] [=invalid argument=].
    23. - For each |sample| in |samples|: -
        -
      1. - If |sample| is not a [=string=] and a valid {{PressureState}}, return [=error=] with [=error code|WebDriver error code=] [=invalid argument=]. -
        2. -
      - For each |sample| in |samples|: -
        -
      1. - [=queue/Enqueue=] |sample| to |virtualPressureSource|'s [=pending samples=]. -
        2. -
      + Set |virtualPressureSource|'s [=pending sample=] to |sample|. +
      24. +
    24. + In an [=implementation-defined=] way, run the [=data collection=] steps.
    25. Return [=success=] with data null.

    - -

    Examples From 3dbb08835261adb271956ee82c37c3ac9300c93e Mon Sep 17 00:00:00 2001 From: Raphael Kubo da Costa Date: Thu, 30 May 2024 14:00:43 +0200 Subject: [PATCH 11/44] Fix [=map/Remove=] syntax --- index.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.html b/index.html index 4c22bf7..ca515d8 100644 --- a/index.html +++ b/index.html @@ -1808,7 +1808,7 @@

    Let |topLevelVirtualPressureSourceMapping| be the |topLevelTraversable|'s [=virtual pressure source mapping=].

  • - [map/Remove] |topLevelVirtualPressureSourceMapping|[|virtualPressureSourceType|]. + [=map/Remove=] |topLevelVirtualPressureSourceMapping|[|virtualPressureSourceType|].
  • Return [=success=] with data null. From c92a958a7418525fd1a512c76dc102a058b9e30a Mon Sep 17 00:00:00 2001 From: Raphael Kubo da Costa Date: Thu, 30 May 2024 16:59:37 +0200 Subject: [PATCH 12/44] Remove needless comma --- index.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.html b/index.html index ca515d8..a3edee4 100644 --- a/index.html +++ b/index.html @@ -258,7 +258,7 @@

    Sampling and Reporting Rate

    For automation purposes, a [=platform collector=] must have the ability to connect to - [=virtual pressure sources=] and user their simulated data, as already [=adjusted pressure states=] + [=virtual pressure sources=] and user their simulated data as already [=adjusted pressure states=] instead of actual platform data.

    From 1768ef5c4efbf106c87e9fe7036e54f1c10f9f58 Mon Sep 17 00:00:00 2001 From: Raphael Kubo da Costa Date: Thu, 30 May 2024 15:28:03 +0200 Subject: [PATCH 13/44] Remove virtual pressure source's source type property It was not being used anywhere; the source type is always when manipulating the virtual pressure source mapping, which uses source types as keys. --- index.html | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/index.html b/index.html index a3edee4..1082dc5 100644 --- a/index.html +++ b/index.html @@ -1664,9 +1664,6 @@

    Each [=virtual pressure source=] has:

      -
    • - a [=source type=]. -
    • a pending sample of type {{PressureState}} or null, which is initially null.
      • @@ -1787,8 +1784,8 @@

      - This [=extension command=] deletes a given [=source type=] of [=virtual pressure source=], meaning that, - if available, data will be delivered the regular way, by non-virtual means. + 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: From 417dcb41ae657b680d3881e48b4b8c966e76e1b4 Mon Sep 17 00:00:00 2001 From: Raphael Kubo da Costa Date: Thu, 30 May 2024 15:33:46 +0200 Subject: [PATCH 14/44] Use data-dfn-for for concepts scoped to virtual pressure source This makes it more clear when writing the spec that this is a concept related to a virtual pressure source rather than a general one. --- index.html | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/index.html b/index.html index 1082dc5..f21eb29 100644 --- a/index.html +++ b/index.html @@ -1134,11 +1134,13 @@

      Data Collection and Delivery

    • - If |virtualPressureSource| is not null, let |state:PressureState| and |data| - be |virtualPressureSource|'s [=pending sample=]. + If |virtualPressureSource| is not null, let |state:PressureState| and + |data| be |virtualPressureSource|'s [=virtual pressure source/pending + sample=].
    • - Set |virtualPressureSource|'s [=pending sample=] to null. + Set |virtualPressureSource|'s [=virtual pressure source/pending + sample=] to null.
    • If |data| is null, abort these steps. @@ -1665,7 +1667,8 @@

      Each [=virtual pressure source=] has:
      • - a pending sample of type {{PressureState}} or null, which is initially null. + a pending sample of + type {{PressureState}} or null, which is initially null.

      @@ -1835,7 +1838,7 @@

      This [=extension command=] allows updating the state of a [=virtual pressure source=] by pushing - a new [=pending sample=]. + a new [=virtual pressure source/pending sample=].

    • - Set |virtualPressureSource|'s [=pending sample=] to |sample|. + Set |virtualPressureSource|'s [=virtual pressure source/pending sample=] to |sample|.
    • In an [=implementation-defined=] way, run the [=data collection=] steps. From 8b8f2825dcd43b18f8e746cdec08acbe6e160c44 Mon Sep 17 00:00:00 2001 From: Raphael Kubo da Costa Date: Thu, 30 May 2024 16:25:05 +0200 Subject: [PATCH 15/44] Move retrieval of a virtual pressure source from a global to a separate algorithm This makes it possible to invoke it from multiple locations in preparation for supporting adding a virtual pressure source that reports itself as non-existent. While here: add `class="algorithm"` to the "data collection" algorithm. --- index.html | 65 ++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 43 insertions(+), 22 deletions(-) diff --git a/index.html b/index.html index f21eb29..c8f4cc5 100644 --- a/index.html +++ b/index.html @@ -1085,30 +1085,17 @@

      Supporting algorithms

      • - -
      -

      Data Collection and Delivery

      - [=Data collection=] from a [=platform collector=] can be activated and deactivated in an - [=implementation-defined=] manner per [=source type=] and [=global object=]. -

      - -

      - The data collection steps given |relevantGlobal| as input, are run when - the |relevantGlobal| associated [=platform collector=] needs to obtain new |data| - for a [=source type=] |source:PressureSource| and are as follows: -

        -
      1. - Let |virtualPressureSource| be null. -
        2. + 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. +
          +
        1. Let |topLevelTraversable| be null.
        2. If |relevantGlobal| is a {{Window}} object:
          1. - Let |topLevelTraversable| be |relevantGlobal|'s [=Window/navigable=]'s [=top-level traversable=]. + Set |topLevelTraversable| to |relevantGlobal|'s [=Window/navigable=]'s [=top-level traversable=].
          3. @@ -1119,19 +1106,53 @@

          Data Collection and Delivery

          Let |owningDocuments| be |relevantGlobal|'s [=owning document set=].
        3. - If |owningDocuments| is empty, abort these steps. + If |owningDocuments| is empty, return null.
        4. - Let |topLevelTraversable| be |owningDocuments|[0]'s [=node navigable=]'s [=top-level traversable=]. + Set |topLevelTraversable| to |owningDocuments|[0]'s [=node navigable=]'s [=top-level traversable=].
        +
      2. + If |topLevelTraversable| is null, return null. +
      3. Let |topLevelVirtualPressureSourceMapping| be the |topLevelTraversable|'s [=virtual pressure source mapping=].
      4. - Set |virtualPressureSource| to |topLevelVirtualPressureSourceMapping|[|source|]. + Let |virtualPressureSource| be null.
        5. +
      5. + If |topLevelVirtualPressureSourceMapping| [=map/contains=] |source|: +
          +
        1. + Set |virtualPressureSource| to |topLevelVirtualPressureSourceMapping|[|source|]. +
          2. +
        +
        6. +
      6. + Return |virtualPressureSource|. +
        7. +
      +

      +
      +
      +

      Data Collection and Delivery

      +

      + [=Data collection=] from a [=platform collector=] can be activated and deactivated in an + [=implementation-defined=] manner per [=source type=] and [=global object=]. +

      + +

      + The data collection steps given |relevantGlobal| as input, are run when + the |relevantGlobal| associated [=platform collector=] needs to obtain new |data| + for a [=source type=] |source:PressureSource| and are as follows: +

        +
      1. + Let |virtualPressureSource| be the result of invoking [=get a virtual pressure source=] with |source| and |relevantGlobal|.
      2. If |virtualPressureSource| is not null, let |state:PressureState| and From afcabae581f478015b8125095be8aab67772ed9d Mon Sep 17 00:00:00 2001 From: Raphael Kubo da Costa Date: Thu, 30 May 2024 16:53:46 +0200 Subject: [PATCH 16/44] virtual pressure source: Add "can provide samples flag" boolean This flag can be set in the "create virtual pressure source" endpoint, where it is set to true by default. When false, it causes calls to PressureObserver.observe() to reject with NotSupportedError when attempting to use the given virtual pressure source. --- index.html | 53 ++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 52 insertions(+), 1 deletion(-) diff --git a/index.html b/index.html index c8f4cc5..c822d82 100644 --- a/index.html +++ b/index.html @@ -602,8 +602,34 @@

        The observe() method

      3. Run the following steps [=in parallel=]:
          +
        1. - If |source:PressureSource| is not a [=valid source type=], + Let |supported| be true. +
          2. +
        2. + Let |virtualPressureSource| be the result of invoking [=get a + virtual pressure source=] with |source| and |relevantGlobal|. +
          3. +
        3. + If |virtualPressureSource| is not null: +
            +
          1. + Set |supported| to |virtualPressureSource|'s [=virtual + pressure source/can provide samples flag=]. +
            2. +
          +
          4. +
        4. + Otherwise, if |source| is not a [=valid source type=]: +
            +
          1. + Set |supported| to false. +
            2. +
          +
          5. +
        5. + If |supported| is false, [=queue a global task=] on the [=PressureObserver task source=] given |relevantGlobal| to reject |promise| {{NotSupportedError}} and abort these steps. @@ -1691,6 +1717,10 @@

          a pending sample of type {{PressureState}} or null, which is initially null.

          6. +
        6. + a can provide samples + flag, a boolean. +

    @@ -1753,6 +1783,17 @@

    yes + + + supported + + + Boolean + + + no + +

    The [=remote end steps=] given |session|, |URL variables| and |parameters| are: @@ -1776,9 +1817,19 @@

    If |topLevelVirtualPressureSourceMapping| contains |virtualPressureSourceType|, return [=error=] with [=error code|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 [=virtual pressure source/can provide + samples flag=] to |supported|. +
  • Set |topLevelVirtualPressureSourceMapping|[|virtualPressureSourceType|] to |virtualPressureSource|.
    • From 8e9809cdc4addb53f07dce1bdb4e0372ad32ba76 Mon Sep 17 00:00:00 2001 From: Raphael Kubo da Costa Date: Thu, 30 May 2024 17:02:37 +0200 Subject: [PATCH 17/44] get virtual pressure source: Add assertion for owningDocument's size Merely for readability; if we reach the assertion, it means there must be exactly one element in the owning set (only shared workers would have more than one owning document). --- index.html | 3 +++ 1 file changed, 3 insertions(+) diff --git a/index.html b/index.html index c822d82..16b0c8d 100644 --- a/index.html +++ b/index.html @@ -1134,6 +1134,9 @@

    Supporting algorithms

  • If |owningDocuments| is empty, return null.
    • +
  • + [=Assert=]: |owningDocuments|'s [=set/size=] is 1. +
  • Set |topLevelTraversable| to |owningDocuments|[0]'s [=node navigable=]'s [=top-level traversable=].
    • From 61653144a1e18fc5407f5019fa2d5c926de3a7b8 Mon Sep 17 00:00:00 2001 From: Raphael Kubo da Costa Date: Thu, 30 May 2024 17:38:19 +0200 Subject: [PATCH 18/44] Improvements to the "data collection" algorithm from my PR review - Get rid of `|data|` altogether. Specifying a return variable in the algorithm declaration is at the very least unusual. Furthermore, `|data|` and `|state|` were serving the same purpose in the virtual pressure source case while not working correctly in the non-virtual one at all: in the non-virtual case, `|data|` would always be null and the entire algorithm would abort. Furthermore, even if it did not, the subsequent step was reading `|data|` without ever writing to it first. - Stop setting a virtual platform sensor's "pending sample" to null after reading it. It is not necessary; if the same sample is sent on a later call, the other algorithms (like "has change in data") should take care of ignoring it instead. - Formatting: add missing `

    ` tags to the `

    The data collection steps given |relevantGlobal| as input, are run when - the |relevantGlobal| associated [=platform collector=] needs to obtain new |data| + the |relevantGlobal| associated [=platform collector=] needs to obtain new data for a [=source type=] |source:PressureSource| and are as follows:

    1. - Let |virtualPressureSource| be the result of invoking [=get a virtual pressure source=] with |source| and |relevantGlobal|. + Let |state:PressureState| be null.
    2. - If |virtualPressureSource| is not null, let |state:PressureState| and - |data| be |virtualPressureSource|'s [=virtual pressure source/pending - sample=]. + Let |virtualPressureSource| be the result of invoking [=get a virtual pressure source=] with |source| and |relevantGlobal|.
    3. - Set |virtualPressureSource|'s [=virtual pressure source/pending - sample=] to null. + If |virtualPressureSource| is not null: +
        +
      1. + Set |state| to |virtualPressureSource|'s [=virtual pressure + source/pending sample=]. +
        2. +
      2. + If |state| is null, abort these steps. +
        3. +
    4. - If |data| is null, abort these steps. + Otherwise: +
        +
      1. + Set |state| to an [=adjusted pressure state=] calculated from + |source| and any [=implementation-defined=] platform data related + to |source|. + +
        2. +
    5. - Otherwise, let |state:PressureState| be an [=adjusted pressure state=] given |data| and |source|. - + [=Assert=]: |state| is not null.
    6. - Let |timestamp:DOMHighResTimeStamp| be a timestamp representing the time the |data| was + Let |timestamp:DOMHighResTimeStamp| be a timestamp representing the time the |state| was collected by the |relevantGlobal|'s [=platform collector=].
    7. From 4a5757a3d2284cb8d485295a9763a69f047aafe0 Mon Sep 17 00:00:00 2001 From: Raphael Kubo da Costa Date: Thu, 30 May 2024 17:53:46 +0200 Subject: [PATCH 19/44] Add missing apostrophe --- index.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.html b/index.html index f69ecff..e3d96ec 100644 --- a/index.html +++ b/index.html @@ -1177,7 +1177,7 @@

      Data Collection and Delivery

      The data collection steps given |relevantGlobal| as input, are run when - the |relevantGlobal| associated [=platform collector=] needs to obtain new data + |relevantGlobal|'s associated [=platform collector=] needs to obtain new data for a [=source type=] |source:PressureSource| and are as follows:

      1. From 4f79b6241c384c882e4bcbca1625d1bac944f50b Mon Sep 17 00:00:00 2001 From: Raphael Kubo da Costa Date: Mon, 3 Jun 2024 17:24:05 +0200 Subject: [PATCH 20/44] Fix typo: user -> use --- index.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.html b/index.html index e3d96ec..8e35d41 100644 --- a/index.html +++ b/index.html @@ -258,7 +258,7 @@

        Sampling and Reporting Rate

        For automation purposes, a [=platform collector=] must have the ability to connect to - [=virtual pressure sources=] and user their simulated data as already [=adjusted pressure states=] + [=virtual pressure sources=] and use their simulated data as already [=adjusted pressure states=] instead of actual platform data.

        From c01a9a913d9cc0d85b9043f5eefe5924b67fd40e Mon Sep 17 00:00:00 2001 From: Raphael Kubo da Costa Date: Mon, 3 Jun 2024 17:26:41 +0200 Subject: [PATCH 21/44] Fix platform collector cardinality, define pressure source and activation/deactivation This addresses https://github.com/w3c/compute-pressure/pull/265#discussion_r1616265626 by properly defining several concepts in one change: - "Pressure source" is now a proper ``. It is similar to a "device sensor" in the Generic Sensor API spec, in that it works as the concept closest to the OS/hardware and retrieves some abstract telemetry data that is fed to one or more platform collectors. A virtual pressure source is a pressure source. - Platform collector's granularity has been fixed: there isn't one per global, but rather one per source type. To make it easier to follow, a global now has a "platform collector mapping" rather than just an associated platform collector. - Each platform collector now has some associated data: an "associated pressure source", which is the pressure source it retrieves data from, as well as an "activated" flag that is used when activating/deactivating data collection. With these new building blocks, we can fix and/or properly define some concepts that have been unclear so far: - A null associated pressure source indicates that a given pressure source is not available. This is used, for example, in `PressureObserver.observe()`, which is now responsible for creating a platform collector when one is not available in its global and attempting to set the platform collector's associated pressure source to either a virtual pressure source or a real one. When neither can be found, it remains null, which signals that `observe()` must reject with NotSupportedError. Previously (see #273), the `observe()` steps simply checked if `|source|` was a "valid source type", which did not properly reflect the potentially asynchronous checks involved in the real pressure source case. - The absence of an entry for a given source type in the "platform collector mapping" indicates that `PressureObserver.observe()` must attempt to create a new platform collector as described above. An existing "platform collector mapping" entry is removed only by calls to `disconnect()` and `unobserve()` as well as when a document is no longer fully active or a worker's closing flag is set to true. Conceptually, this indicates more clearly that once a platform collector is created in `observe()` it will continue using the same associated pressure source. In other words, if `observe()` is called before "create virtual pressure source", all observers for the same source type will continue using a real pressure source until they all disconnect (and vice-versa). - A virtual pressure source keeps track of connected platform collectors so that it can set their associated pressure source to null when it is removed before they disconnect. This is used in the new data collection algorithm described below. - The data collection steps have been revamped. - "Data collection" itself has not changed much: it tries to get a platform collector's pressure source if one exists, read data from it and dispatch it to observers. - We finally have proper definitions for what it means to activate and deactivate data collection. The steps themselves do not do much besides making sure 1) a platform collector for the desired source exists and 2) these steps cannot run more than once for a platform collector. The "deactivate data collection" steps also takes care of removing a collector from a virtual pressure source's connected platform collectors set. --- index.html | 273 ++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 219 insertions(+), 54 deletions(-) diff --git a/index.html b/index.html index d1b5d30..759f2c5 100644 --- a/index.html +++ b/index.html @@ -243,18 +243,38 @@

        Sampling and Reporting Rate

        Platform primitives

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

        - For this specification's purposes, there is one separate [=platform collector=] per - [=global object=], which can support telemetry for different source types - defined by {{PressureSource}}. + A platform collector is an abstract interface responsible for + obtaining telemetry samples from a [=pressure source=], translating them + into [=pressure states=] and providing them to the [=user agent=].

        - From the implementation perspective it can be treated as a software proxy for the - corresponding hardware counters or underlying telemetry framework, and it can make use - of data fusion with data from additional sources if that provides better results. + A [=platform collector=] has the following associated data: +

        +
          +
        • + an associated pressure + source, which is a [=pressure source=] or null. +
          • +
        • + an activated boolean flag, + initially false. +
          • +
        +

        + The format of the data provided by a [=pressure source=] is + [=implementation-defined=], and so is the process through which a + [=platform collector=] translates it into a [=pressure state=]. +

        +

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

        For automation purposes, a [=platform collector=] must have the ability to connect to @@ -358,7 +378,8 @@

        a registered observer list per supported [=source type=], which is initially empty.

      2. - a platform collector as detailed in [[[#platform-primitives]]]. + a platform collector mapping, an [=ordered map=] of [=source + types=] to [=platform collectors=].
        3. A registered observer consists of an observer (a {{PressureObserver}} object). @@ -602,40 +623,71 @@

        The observe() method

      3. Run the following steps [=in parallel=]:
          - -
        1. - Let |supported| be true. -
        2. - Let |virtualPressureSource| be the result of invoking [=get a - virtual pressure source=] with |source| and |relevantGlobal|. -
          3. -
        3. - If |virtualPressureSource| is not null: + If |relevantGlobal|'s [=platform collector mapping=] does not + [=map/contain=] |source|:
          1. - Set |supported| to |virtualPressureSource|'s [=virtual - pressure source/can provide samples flag=]. + Let |newCollector| be a new [=platform collector=] whose + [=platform collector/associated pressure source=] is null. +
            2. +
          2. + Let |virtualPressureSource| be the result of invoking [=get a + virtual pressure source=] with |source| and |relevantGlobal|. +
            3. +
          3. + If |virtualPressureSource| is not null: +
              +
            1. + If |virtualPressureSource|'s [=virtual pressure + source/can provide samples flag=] is true: +
                +
              1. + Set |newCollector|'s [=platform collector/associated + pressure source=] to |virtualPressureSource|. +
                2. +
              2. + [=set/Append=] |newCollector| to + |virtualPressureSource|'s [=virtual pressure + source/connected platform collectors=]. +
                3. +
              +
              2. +
            +
            4. +
          4. + Otherwise: +
              +
            1. + Let |realPressureSource| be an [=implementation-defined=] + [=pressure source=] that provides telemetry information + about |source|, or null if none can be found. +
              2. +
            2. + Set |newCollector|'s [=platform collector/associated + pressure source=] to |realPressureSource|. +
              3. +
            5. -
          -
          4. -
        4. - Otherwise, if |source| is not a [=valid source type=]: -
          1. - Set |supported| to false. + Set |relevantGlobal|'s [=platform collector + mapping=][|source|] to |newCollector|.
        5. - If |supported| is false, - [=queue a global task=] on the [=PressureObserver task source=] - given |relevantGlobal| - to reject |promise| {{NotSupportedError}} and abort these steps. + Let |platformCollector| be |relevantGlobal|'s [=platform collector + mapping=][|source|].
        6. - Activate [=data collection=] from |relevantGlobal|'s [=platform collector=] of |source| data to |relevantGlobal|. + If |platformCollector|'s [=platform collector/associated pressure + source=] is null, [=queue a global task=] on the + [=PressureObserver task source=] given |relevantGlobal| to reject + |promise| {{NotSupportedError}} and abort these steps. +
          7. +
        7. + Invoke [=activate data collection=] with |source| and + |relevantGlobal|.
        8. [=Queue a global task=] on the [=PressureObserver task source=] given @@ -646,7 +698,7 @@

          The observe() method

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

            The unobserve() method

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

          The disconnect() method

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

        Supporting algorithms

        Data Collection and Delivery

        - [=Data collection=] from a [=platform collector=] can be activated 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 collection steps given |relevantGlobal| as input, are run when - |relevantGlobal|'s associated [=platform collector=] needs to obtain new data - for a [=source type=] |source:PressureSource| and 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. + If |platformCollector|'s [=platform collector/associated pressure + source=] is a [=virtual pressure source=]: +
            +
          1. + [=set/Remove=] |platformCollector| from its [=platform + collector/associated pressure source=]'s [=virtual pressure + source/connected platform collectors=]. +
            2. +
          +
          7. +
        7. + Otherwise, perform any [=implementation-defined=] steps to signal to + |platformCollector|'s [=platform collector/associated pressure source=] + to stop retrieving telemetry data. +
          8. +
        +

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

        1. - Let |state:PressureState| be null. + Let |pressureSource| be |platformCollector|'s [=platform + collector/associated pressure source=].
        2. - Let |virtualPressureSource| be the result of invoking [=get a virtual pressure source=] with |source| and |relevantGlobal|. + If |pressureSource| is null, abort these steps.
        3. - If |virtualPressureSource| is not null: + Let |state:PressureState| be null. +
          4. +
        4. + If |pressureSource| is a [=virtual pressure source=]:
          1. - Set |state| to |virtualPressureSource|'s [=virtual pressure + Set |state| to |pressureSource|'s [=virtual pressure source/pending sample=]. -
            2. +
          2. If |state| is null, abort these steps.
            3. @@ -1404,7 +1534,12 @@

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

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

            Handling changes to worker status

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

            Virtual Pressure Source

            - A virtual pressure source simulates the behavior of a real pressure source in controlled ways. + A virtual pressure source simulates the behavior of a real [=pressure source=] 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=]. +

            Each [=virtual pressure source=] has:

              @@ -1776,6 +1921,10 @@

              a can provide samples flag, a boolean. +
            • + a connected platform + collectors [=set=] of [=platform collectors=]. +

            @@ -1810,7 +1959,7 @@

            This [=extension command=] creates a new [=virtual pressure source=] of a specified [=source type=]. Calls to {{PressureObserver/observe()}} from {{PressureObserver}} instances of the same [=source type=] will cause this [=virtual pressure source=] to be used as their - backing pressure source until [[[#delete-virtual-pressure-source]]] is run. + backing [=pressure source=] until [[[#delete-virtual-pressure-source]]] is run.

            @@ -1934,6 +2083,19 @@

          3. Let |topLevelVirtualPressureSourceMapping| be the |topLevelTraversable|'s [=virtual pressure source mapping=].
            4. +
          4. + Let |pressureSource| be |topLevelVirtualPressureSourceMapping|[|virtualPressureSourceType|]. +
            5. +
          5. + [=set/For each=] |platformCollector| of |pressureSource|'s [=virtual + pressure source/connected platform collectors=]: +
              +
            1. + Set |platformCollector|'s [=platform collector/associated pressure + source=] to null. +
              2. +
            +
          6. [=map/Remove=] |topLevelVirtualPressureSourceMapping|[|virtualPressureSourceType|].
            7. @@ -2037,7 +2199,10 @@

            Set |virtualPressureSource|'s [=virtual pressure source/pending sample=] to |sample|.
          7. - In an [=implementation-defined=] way, run the [=data collection=] steps. + In an [=implementation-defined=] way, make |virtualPressureSource|'s + [=virtual pressure source/pending sample=] available to + |virtualPressureSource|'s [=virtual pressure source/connected platform + collectors=].
          8. Return [=success=] with data null. From 9e45f07a402920d39821be00c3ab1c8ef320f9b4 Mon Sep 17 00:00:00 2001 From: Raphael Kubo da Costa Date: Tue, 4 Jun 2024 14:09:33 +0200 Subject: [PATCH 22/44] Define "source type" (singular) --- index.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.html b/index.html index 759f2c5..84ba174 100644 --- a/index.html +++ b/index.html @@ -245,7 +245,7 @@

            Sampling and Reporting Rate

            A pressure source is an abstract, [=implementation-defined=] interface to hardware counters or an underlying telemetry framework that - provides information about a source types + provides information about a source type defined by {{PressureSource}}. A [=pressure source=] can make use of data fusion with data from additional sources if that provides better results.

            From 126995b84bb585105e732888e5b7556ede77c43f Mon Sep 17 00:00:00 2001 From: Raphael Kubo da Costa Date: Tue, 4 Jun 2024 13:47:23 +0200 Subject: [PATCH 23/44] Add a note explaining when virtual pressure sources do have an effect --- index.html | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/index.html b/index.html index 84ba174..aa135ef 100644 --- a/index.html +++ b/index.html @@ -1931,6 +1931,29 @@

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

            +

            Extension Commands

            From 19e894ef88f4f096a931143498c53709faf5b686 Mon Sep 17 00:00:00 2001 From: Raphael Kubo da Costa Date: Fri, 7 Jun 2024 13:51:59 +0200 Subject: [PATCH 24/44] data collection: Say adjusted pressure state calculation is implementation-defined --- index.html | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/index.html b/index.html index aa135ef..5a28e95 100644 --- a/index.html +++ b/index.html @@ -1351,9 +1351,9 @@

            Data Collection and Delivery

            Otherwise:
            1. - Set |state| to an [=adjusted pressure state=] calculated from - |source| and any [=implementation-defined=] platform data related - to |source|. + Set |state| to an [=adjusted pressure state=] calculated in an + [=implementation-defined=] manner from |source| and any + [=implementation-defined=] platform data related to |source|.

            9. This [=extension command=] allows updating the state of a [=virtual pressure source=] by pushing - a new [=virtual pressure source/pending sample=]. + a new [=pending sample descriptor=].

            -
          9. - Set |rawTimestamp| to |sample|'s [=pressure source - sample/timestamp=]. -

        5. [=Assert=]: |state| is not null.
          6. +
        6. + Let |rawTimestamp| be |sample|'s [=pressure source + sample/timestamp=]. +
        7. Let |timeValue| be the [=relative high resolution time=] based on |rawTimestamp| and |relevantGlobal|. @@ -1942,35 +1938,21 @@

          Virtual Pressure Source

          - A virtual pressure source simulates the behavior of a real [=pressure source=] in controlled ways. - It reports pressure changes to zero or more [=platform collectors=] connected to it. + 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=]. + must be processed into [=pressure states=] by a [=platform collector=]. In + other words, a [=virtual pressure source=]'s [=pressure source sample=]'s + [=pressure source sample/data=] is a {{PressureState}}.

          - A pending sample descriptor is a [=struct=] with the following - [=struct/items=]: + In addition to the data associated with all [=pressure sources=] (such as + [=pressure source sample=]), each [=virtual pressure source=] has:

            -
          • - state, a - {{PressureState}}. -
            • -
          • - timestamp, a - [=monotonic clock/unsafe current time=] from the [=monotonic clock=]. -
            • -
          -

          -

          - Each [=virtual pressure source=] has: -

            -
          • - a pending sample, - which is a [=pending sample descriptor=] or null. -
          • a can provide samples boolean flag. @@ -2215,7 +2197,7 @@

            This [=extension command=] allows updating the state of a [=virtual pressure source=] by pushing - a new [=pending sample descriptor=]. + a new [=pressure source sample=].

          • - Set |virtualPressureSource|'s [=virtual pressure source/pending sample=] - to a new [=pending sample descriptor=] whose [=pending sample - descriptor/state=] is |sample| and [=pending sample - descriptor/timestamp=] is the [=unsafe shared current time=]. + Set |virtualPressureSource|'s [=pressure source/latest sample=] to a new + [=pressure source sample=] whose [=pressure source sample/data=] is + |sample| and [=pressure source sample/timestamp=] is the [=unsafe shared + current time=].
          • In an [=implementation-defined=] way, make |virtualPressureSource|'s - [=virtual pressure source/pending sample=] available to - |virtualPressureSource|'s [=virtual pressure source/connected platform - collectors=]. + [=pressure source/latest sample=] available to |virtualPressureSource|'s + [=virtual pressure source/connected platform collectors=].
          • Return [=success=] with data null. From e63d26b3d11fa426057be7673ee73b9acf523e2f Mon Sep 17 00:00:00 2001 From: Raphael Kubo da Costa Date: Thu, 13 Jun 2024 16:05:13 +0200 Subject: [PATCH 31/44] Do not surround null with `` tags This was copied from the Generic Sensor spec and not done in other places, so drop the tag for uniformity. --- index.html | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/index.html b/index.html index 0940130..a337334 100644 --- a/index.html +++ b/index.html @@ -2108,7 +2108,7 @@

            Set |topLevelVirtualPressureSourceMapping|[|virtualPressureSourceType|] to |virtualPressureSource|.

          • - Return [=success=] with data null. + Return [=success=] with data null.

        @@ -2170,7 +2170,7 @@

        [=map/Remove=] |topLevelVirtualPressureSourceMapping|[|virtualPressureSourceType|].

      4. - Return [=success=] with data null. + Return [=success=] with data null.
      @@ -2277,7 +2277,7 @@

      [=virtual pressure source/connected platform collectors=].

    8. - Return [=success=] with data null. + Return [=success=] with data null.
    From b98c68ddc8accf514e9fd97b6e5fc3a12a19dc60 Mon Sep 17 00:00:00 2001 From: Raphael Kubo da Costa Date: Thu, 13 Jun 2024 16:07:31 +0200 Subject: [PATCH 32/44] Refer to a definition of "empty" in the context of an ordered set --- index.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.html b/index.html index a337334..1a129bd 100644 --- a/index.html +++ b/index.html @@ -1241,7 +1241,7 @@

    Supporting algorithms

    Let |owningDocuments| be |relevantGlobal|'s [=owning document set=].
  • - If |owningDocuments| is empty, return null. + If |owningDocuments| is [=set/empty=], return null.
  • [=Assert=]: |owningDocuments|'s [=set/size=] is 1. From a58799e20bbe8f900bc3ca9a0bec5d740d60757c Mon Sep 17 00:00:00 2001 From: Raphael Kubo da Costa Date: Thu, 13 Jun 2024 16:10:53 +0200 Subject: [PATCH 33/44] observe(): Add a type for `|virtualPressureSource|` --- index.html | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/index.html b/index.html index 1a129bd..aa39685 100644 --- a/index.html +++ b/index.html @@ -662,8 +662,9 @@

    The observe() method

    [=platform collector/associated pressure source=] is null.
  • - Let |virtualPressureSource| be the result of invoking [=get a - virtual pressure source=] with |source| and |relevantGlobal|. + Let |virtualPressureSource:virtual pressure source or null| + be the result of invoking [=get a virtual pressure source=] + with |source| and |relevantGlobal|.
  • If |virtualPressureSource| is not null: From 93beaa05487f42021aaf9abf106bc36db1c8e378 Mon Sep 17 00:00:00 2001 From: Raphael Kubo da Costa Date: Thu, 13 Jun 2024 16:27:38 +0200 Subject: [PATCH 34/44] automation: Check virtualPressureSourceType against "supported source types" This ensures that the types accepted in automation are the same which are returned by `PressureObserver.knownSources`. Whether this is really desired can be worked out later. --- index.html | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/index.html b/index.html index aa39685..fd81c64 100644 --- a/index.html +++ b/index.html @@ -2079,7 +2079,9 @@

    get a property "type" from |parameters|.

  • - If |virtualPressureSourceType| is not a [=string=], return [=error=] with [=error code|WebDriver error code=] [=invalid argument=]. + If the [=user agent=]'s [=supported source types=] does not + [=list/contain=] |virtualPressureSourceType|, return [=error=] with + [=error code|WebDriver error code=] [=invalid argument=].
  • Let |topLevelTraversable| be the current browsing @@ -2145,7 +2147,9 @@

    Let |virtualPressureSourceType| be the value of the |URL variables|["type"].

  • - If |virtualPressureSourceType| is not a [=valid source type=], return [=error=] with [=error code|WebDriver error code=] [=invalid argument=]. + If the [=user agent=]'s [=supported source types=] does not + [=list/contain=] |virtualPressureSourceType|, return [=error=] with + [=error code|WebDriver error code=] [=invalid argument=].
  • Let |topLevelTraversable| be the current browsing @@ -2242,7 +2246,9 @@

    Let |virtualPressureSourceType| be the value of the |URL variables|["type"].

  • - If |virtualPressureSourceType| is not a [=valid source type=], return [=error=] with [=error code|WebDriver error code=] [=invalid argument=]. + If the [=user agent=]'s [=supported source types=] does not + [=list/contain=] |virtualPressureSourceType|, return [=error=] with + [=error code|WebDriver error code=] [=invalid argument=].
  • Let |topLevelTraversable| be the current browsing From bc3f3cd3a3e563f666ca01d7ad47e70ab50787ab Mon Sep 17 00:00:00 2001 From: Raphael Kubo da Costa Date: Thu, 13 Jun 2024 16:52:49 +0200 Subject: [PATCH 35/44] Add missing "a" in sentence --- index.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.html b/index.html index fd81c64..1001b12 100644 --- a/index.html +++ b/index.html @@ -307,7 +307,7 @@

    Sampling and Reporting Rate

    For automation purposes, a [=platform collector=] must have the ability to - connect to [=virtual pressure sources=] and use their simulated data + connect to [=virtual pressure sources=] and use their simulated data as [=pressure states=] rather than raw platform data that must be transformed into an [=adjusted pressure state=].

    From 32d3d9fc8a12e6564fbb34057216acb5e4700968 Mon Sep 17 00:00:00 2001 From: Raphael Kubo da Costa Date: Thu, 13 Jun 2024 17:04:00 +0200 Subject: [PATCH 36/44] s/better/more precise/ --- index.html | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/index.html b/index.html index 1001b12..55670eb 100644 --- a/index.html +++ b/index.html @@ -247,7 +247,8 @@

    Sampling and Reporting Rate

    interface to hardware counters or an underlying telemetry framework that provides information about a source type defined by {{PressureSource}}. A [=pressure source=] can make use of data - fusion with data from additional sources if that provides better results. + fusion with data from additional sources if that provides more precise + results.

    The telemetry information provided by a [=pressure source=] is represented From 5c966ff1ff2d9d3c9786f6737fbf07583485e39a Mon Sep 17 00:00:00 2001 From: Raphael Kubo da Costa Date: Thu, 13 Jun 2024 17:09:32 +0200 Subject: [PATCH 37/44] s/translate/transform/ --- index.html | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/index.html b/index.html index 55670eb..3ddc84b 100644 --- a/index.html +++ b/index.html @@ -281,7 +281,7 @@

    Sampling and Reporting Rate

    A platform collector is an abstract interface responsible for - obtaining telemetry samples from a [=pressure source=], translating them + obtaining telemetry samples from a [=pressure source=], transforming them into [=pressure states=] and providing them to the [=user agent=].

    @@ -300,7 +300,7 @@

    Sampling and Reporting Rate

    The format of the data provided by a [=pressure source=] is [=implementation-defined=], and so is the process through which a - [=platform collector=] translates it into a [=pressure state=]. + [=platform collector=] transforms it into a [=pressure state=].

    For this specification's purposes, [=platform collectors=] are scoped to a From a2cf3a440857eb47dc7c5802d27bbd7db6095574 Mon Sep 17 00:00:00 2001 From: Raphael Kubo da Costa Date: Thu, 13 Jun 2024 17:30:20 +0200 Subject: [PATCH 38/44] Say "telemetry data" instead of just "information" or "telemetry information" --- index.html | 25 +++++++++++++------------ 1 file changed, 13 insertions(+), 12 deletions(-) diff --git a/index.html b/index.html index 3ddc84b..048aab9 100644 --- a/index.html +++ b/index.html @@ -244,15 +244,15 @@

    Sampling and Reporting Rate

    Platform primitives

    A pressure source is an abstract, [=implementation-defined=] - interface to hardware counters or an underlying telemetry framework that - provides information about a source type + 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.

    - The telemetry information provided by a [=pressure source=] is represented - in this specification as a pressure source sample, a [=struct=] + 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=]:

    • @@ -298,9 +298,10 @@

      Sampling and Reporting Rate

    - The format of the data provided by a [=pressure source=] is - [=implementation-defined=], and so is the process through which a - [=platform collector=] transforms it into a [=pressure state=]. + 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 @@ -308,9 +309,9 @@

    Sampling and Reporting Rate

    For automation purposes, a [=platform collector=] must have the ability to - connect to [=virtual pressure sources=] and use their simulated data as - [=pressure states=] rather than raw platform data that must be transformed - into an [=adjusted pressure state=]. + connect to [=virtual pressure sources=] and use their simulated [=pressure + source sample/data=] as [=pressure states=] rather than raw platform data + that must be transformed into an [=adjusted pressure state=].

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

    The observe() method

    1. Let |realPressureSource| be an [=implementation-defined=] - [=pressure source=] that provides telemetry information - about |source|, or null if none exists. + [=pressure source=] that provides telemetry data about + |source|, or null if none exists.
    2. Set |newCollector|'s [=platform collector/associated From d11d169288b3d64eb427b22e52104d0131fdde52 Mon Sep 17 00:00:00 2001 From: Raphael Kubo da Costa Date: Thu, 13 Jun 2024 17:51:28 +0200 Subject: [PATCH 39/44] Say a pressure source sample's data is a PressureState for virtual pressure sources --- index.html | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/index.html b/index.html index 048aab9..e6c5e7c 100644 --- a/index.html +++ b/index.html @@ -257,7 +257,8 @@

      Sampling and Reporting Rate

      • data: [=contributing - factors=] obtained from the underlying hardware or operating system. + factors=] obtained from the underlying hardware or operating system or, + in the case of a [=virtual pressure source=], a {{PressureState}}.
      • timestamp: the From aaf4da6a87a1f7caa9901b79fb4da660207453ab Mon Sep 17 00:00:00 2001 From: Raphael Kubo da Costa Date: Fri, 14 Jun 2024 10:45:39 +0200 Subject: [PATCH 40/44] Just say "boolean" instead of "boolean flag" --- index.html | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/index.html b/index.html index e6c5e7c..9471474 100644 --- a/index.html +++ b/index.html @@ -294,7 +294,7 @@

        Sampling and Reporting Rate

        source, which is a [=pressure source=] or null.
      • - an activated boolean flag, + an activated boolean, initially false.
      @@ -1959,7 +1959,7 @@

      • a can provide samples - boolean flag. + boolean.
      • a connected platform From 0e4694908e54fa991f5f114bf07c9b47adaedd6d Mon Sep 17 00:00:00 2001 From: Raphael Kubo da Costa Date: Fri, 14 Jun 2024 12:01:28 +0200 Subject: [PATCH 41/44] observe(): Do not always add a collector to the platform collector mapping Avoid adding a platform collector with an empty associated pressure source to the platform collector mapping. Having observe() attempt to find a suitable platform collector every time in this case is not that expensive, and _not_ doing it leads to a situation where inactive observers still need to call unobserve() or disconnect() to remove an entry from the platform collector mapping (to get observe() to try to connect to a platform collector again, for example). --- index.html | 36 ++++++++++++++++++++++++++---------- 1 file changed, 26 insertions(+), 10 deletions(-) diff --git a/index.html b/index.html index 9471474..88f4373 100644 --- a/index.html +++ b/index.html @@ -657,8 +657,20 @@

        The observe() method

        Run the following steps [=in parallel=]:
        1. - If |relevantGlobal|'s [=platform collector mapping=] does not - [=map/contain=] |source|: + 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 @@ -704,18 +716,22 @@

            The observe() method

        4. - Set |relevantGlobal|'s [=platform collector - mapping=][|source|] to |newCollector|. + 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. +
      • - Let |platformCollector| be |relevantGlobal|'s [=platform collector - mapping=][|source|]. -
        • -
      • - If |platformCollector|'s [=platform collector/associated pressure - source=] is null, [=queue a global task=] on the + If |platformCollector| is null, [=queue a global task=] on the [=PressureObserver task source=] given |relevantGlobal| to reject |promise| {{NotSupportedError}} and abort these steps.
        • From 094b061eb4deb990fa75d2acc332ad50e0336748 Mon Sep 17 00:00:00 2001 From: Raphael Kubo da Costa Date: Fri, 14 Jun 2024 13:40:54 +0200 Subject: [PATCH 42/44] Fix indentation --- index.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.html b/index.html index 88f4373..90ccdb4 100644 --- a/index.html +++ b/index.html @@ -1325,7 +1325,7 @@

        Data Collection and Delivery

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

        +

    From 16b08cdec753bab46196df160aab91b7629646d6 Mon Sep 17 00:00:00 2001 From: Raphael Kubo da Costa Date: Fri, 14 Jun 2024 13:56:50 +0200 Subject: [PATCH 43/44] Separate multiple paragraphs with

    tags --- index.html | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/index.html b/index.html index 90ccdb4..64a22d6 100644 --- a/index.html +++ b/index.html @@ -1947,8 +1947,10 @@

    The Compute Pressure API poses a challenge to test authors, as fully - exercising interface requires physical hardware devices that respond in predictable ways. - + 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 From 93c826512ab023f87ab4ef048753dab403b16122 Mon Sep 17 00:00:00 2001 From: Raphael Kubo da Costa Date: Fri, 14 Jun 2024 14:26:06 +0200 Subject: [PATCH 44/44] Make all WEBDRIVER2 citations normative Usage so far had been inconsistent, with some places using the `!` syntax for normative references and others not doing so. --- index.html | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/index.html b/index.html index 64a22d6..8c616fa 100644 --- a/index.html +++ b/index.html @@ -1951,7 +1951,7 @@

    predictable ways.

    - To address this challenge this document defines a [[WEBDRIVER2]] [=extension + 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. @@ -1991,7 +1991,7 @@