Skip to content

Commit

Permalink
Change samplerate to sampleInterval
Browse files Browse the repository at this point in the history
  • Loading branch information
@kenchris
kenchris committed Mar 18, 2024
1 parent d5ece7c commit 2d9d134
Showing 1 changed file with 21 additions and 30 deletions.
51 changes: 21 additions & 30 deletions index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -199,32 +199,34 @@ <h3>Supported sources</h3>
<h3>Sampling and Reporting Rate</h3>
<p>
The <dfn>sampling rate</dfn> for a [=platform collector=] is defined as a rate
at which the [=user agent=] obtains telemetry readings from the underlying platform,
and it might differ from the pressure observers' [=requested sampling rates=].
at which the [=user agent=] obtains telemetry readings from the underlying platform
in Hertz (cycles per second), and it might differ from the rate derived from the
pressure observers' [=requested sample interval=] (in milliseconds) by dividing
1000 with the value.
</p>
<p>
The <dfn>reporting rate</dfn> for a pressure observer is the rate at which it runs
the [=data delivery=] steps.
</p>
<p>
The [=sampling rate=] differs from the [=requested sampling rate=] when the
[=requested sampling rate=] exceeds upper or lower sampling rate bounds
The [=sampling rate=] differs from the [=requested sample interval=] derived rate,
when it exceeds upper or lower sampling rate bounds
supported or accepted by the underlying platform and [=user agent=]<sup>†</sup>.
</p>
<p>
<sup>†</sup>It is recommended that the [=user agent=] limits the [=reporting rate=]
as outlined in [[[#rate-limiting-change-notifications]]].
</p>
<p>
In case the user didn't request a [=sampling rate=], the [=sampling rate=]
In case the user didn't request a sample interval, the [=sampling rate=]
is [=implementation-defined=].
</p>
<aside class="note">
In case there are multiple instances of {{PressureObserver}} active with different
[=requested sampling rates=], it is up to the [=user agent=] to set a
[=requested sample intervals=], it is up to the [=user agent=] to set a
[=platform collector=] level [=sampling rate=] that best fulfills these requests,
while making sure that the [=reporting rate=] of all {{PressureObserver}}s does
not exceed their respective [=requested sampling rates=].
not exceed their respective [=requested sample intervals=].
</aside>
</section>
</section>
Expand Down Expand Up @@ -366,7 +368,7 @@ <h3>
a <dfn>[[\Callback]]</dfn> of type {{PressureUpdateCallback}} set on creation.
</li>
<li>
a <dfn>[[\SampleRate]]</dfn> double set on creation.
a <dfn>[[\SampleInterval]]</dfn> unsigned long long set on creation.
</li>
<li>
a <dfn>[[\PendingObservePromises]]</dfn> [=list=] of zero or more source-promise [=tuples=], initially empty,
Expand Down Expand Up @@ -531,10 +533,7 @@ <h3>The <dfn>constructor()</dfn> method</h3>
Set |this|.{{PressureObserver/[[Callback]]}} to |callback:PressureUpdateCallback|.
</li>
<li>
If |options|["sampleRate"] is less than or equal to 0, throw a {{RangeError}}.
</li>
<li>
Set |this:PressureObserver|.{{PressureObserver/[[SampleRate]]}} to |options|["sampleRate"].
Set |this:PressureObserver|.{{PressureObserver/[[SampleInterval]]}} to |options|["sampleInterval"].
</li>
</ol>
</p>
Expand Down Expand Up @@ -811,25 +810,20 @@ <h3>The <dfn>toJSON</dfn> member</h3>
<h3>The <dfn>PressureObserverOptions</dfn> dictionary</h3>
<pre class="idl">
dictionary PressureObserverOptions {
double sampleRate = 1.0;
[EnforceRange] unsigned long long sampleInterval = 0;
};
</pre>
<section>
<h3>The <dfn>sampleRate</dfn> member</h3>
<h3>The <dfn>sampleInterval</dfn> member</h3>
<p>
The {{PressureObserverOptions/sampleRate}} member represents the <dfn>requested sampling
rate</dfn> expressed in Hz, ie. it represents the number of samples requested to be obtained
from the hardware per second. The [=reporting rate=] will never exceed the [=requested sampling rate=].
The {{PressureObserverOptions/sampleInterval}} member represents the <dfn>requested sample
interval</dfn> expressed in milliseconds, ie. it represents the requested interval between samples
to be obtained from the hardware. The [=reporting rate=] will never exceed the sampling rate which
is obtained by dividing 1000 by the [=requested sample interval=].
</p>
<aside class="note">
<p>
For slow sampling rates (less than 1hz), it is common to use seconds and talk about
period instead of rate. Fortunately, it is easy to convert between the two, as hertz
is rotations per second. If you want to request a sampling rate of 10 seconds, then
just use the value of 0.1.
</p>
<p>
A [=user agent=] might not be able to respect the requested sampling rate. For more information
A [=user agent=] might not be able to respect the requested sample interval. For more information
consult [[[#sampling-and-reporting-rate]]].
</p>
</aside>
Expand Down Expand Up @@ -1023,7 +1017,7 @@ <h3>Supporting algorithms</h3>
</li>
</ol>
<aside class="note">
As there might be multiple observers, each with a different [=requested sampling rate=], the underlying
As there might be multiple observers, each with a different [=requested sample interval=], the underlying
[=platform collector=] will need to use a [=sampling rate=] that fulfills all these requirements. This also
means that not every data sample from the [=platform collector=] needs to be delivered to each active
observer.
Expand All @@ -1039,16 +1033,13 @@ <h3>Supporting algorithms</h3>
Let |record:PressureRecord| be |observer|.{{PressureObserver/[[LastRecordMap]]}}[|source|].
</li>
<li>
Let |sampleRate| be |observer|.{{PressureObserver/[[SampleRate]]}}.
Let |sampleInterval| be |observer|.{{PressureObserver/[[SampleInterval]]}}.
</li>
<li>
Let |timeDeltaMilliseconds:DOMHighResTimeStamp| = |timestamp| - |record|.{{PressureRecord/[[Time]]}}.
</li>
<li>
Let |intervalSeconds| = 1 / |sampleRate|.
</li>
<li>
If (|timeDeltaMilliseconds| / 1000) &ge; |intervalSeconds|, return true, otherwise return false.
If |timeDeltaMilliseconds| &ge; |sampleInterval|, return true, otherwise return false.
</li>
</ol>
The <dfn>has change in data</dfn> steps given the argument |observer:PressureObserver|, |source:PressureSource|,
Expand Down

0 comments on commit 2d9d134

Please sign in to comment.