Bug 1454606 - Document scalar semantics during persistence deserialization. r=Dexter
☠☠ backed out by 324e22546444 ☠ ☠
authorJan-Erik Rediger <jrediger@mozilla.com>
Tue, 29 May 2018 12:53:53 +0200
changeset 474638 6be2c9f129c9966e7ee1cd489a534754362ac662
parent 474637 114fd49040b6bbbb3262fb3459188d903337b5b0
child 474639 324e22546444ba80d38d5899706fdc993efd1f18
push id9374
push userjlund@mozilla.com
push dateMon, 18 Jun 2018 21:43:20 +0000
treeherdermozilla-beta@160e085dfb0b [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewersDexter
bugs1454606
milestone62.0a1
first release with
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
last release without
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
Bug 1454606 - Document scalar semantics during persistence deserialization. r=Dexter MozReview-Commit-ID: 4EHl1atJwea
toolkit/components/telemetry/docs/internals/geckoview.rst
--- a/toolkit/components/telemetry/docs/internals/geckoview.rst
+++ b/toolkit/components/telemetry/docs/internals/geckoview.rst
@@ -36,16 +36,44 @@ contained measurements are loaded in mem
   ``internal-telemetry-geckoview-load-complete`` topic is broadcasted to signal that loading
   is complete.
 
 Once the measurements are restored, their values will be dumped again to the persisted
 measurements file after the update interval expires. This interval is defined by the
 ``toolkit.telemetry.geckoPersistenceTimeout`` preference (defaults to 1 minute), see the
 :doc:`preferences docs <preferences>`.
 
+Scalar Semantics
+~~~~~~~~~~~~~~~~
+
+Data collection can start very early during the application life cycle and might overlap with the persistence deserialization.
+The Telemetry Core therefore takes additional steps to preserve the semantics of scalar operations.
+
+During deserialization of persisted measurements operations on scalar probes are not applied immediately, but recorded into a pending operations list.
+Once deserialization is finished, the pending operations are applied in the order they were recorded.
+This avoids any data race between operations and scalar values are always in a consistent state.
+Snapshots requests will only be fulfilled after the deserialization finished and all pending operations are applied.
+Consumers of the recorded data should therefore never see inconsistent data.
+
+An example:
+
+1. Scalar deserialization is started
+2. "test" scalar is incremented by "10" by the application -> The operation ``[test, add, 10]`` is recorded into the list.
+3. The state of the "test" scalar is loaded off the persistence file, and the value "14" is set.
+4. Deserialization is finished and the pending operations are applied.
+
+   * The "test" scalar is incremented by "10", the value is now "24"
+5. "test" scalar is incremented via "scalarAdd" by 1. Its value is "25"
+
+To stop growing unbounded in memory while waiting for scalar deserialization to finish, pending operations are applied
+immediately if the array reaches a high water mark of 10000 elements.
+At that point the deserialization is considered done and following scalar operatins will be applied immediately.
+In the case of the deserialization still being in progress, it might overwrite recorded values,
+leading to inconsistent data.
+
 The persistence file format
 ---------------------------
 All the supported measurements are serialized to the persistence file using the JSON format.
 The top level entries in the file are the measurement types. Each measurement section contains
 an entry for all the supported processes. Finally, each process section contains the measurement
 specific data required to restore its state in memory.
 
 .. code-block:: js
@@ -141,8 +169,9 @@ The following API is only exposed to the
 Version history
 ---------------
 
 
 - Firefox 62:
 
   - Initial GeckoView support and scalar persistence (`bug 1453591 <https://bugzilla.mozilla.org/show_bug.cgi?id=1453591>`_).
   - Persistence support for histograms (`bug 1457127 <https://bugzilla.mozilla.org/show_bug.cgi?id=1457127>`_).
+  - Preserve the semantics of scalar operations when restoring the persisted state (`bug 1454606 <https://bugzilla.mozilla.org/show_bug.cgi?id=1454606>`_)