Adding upstream version 110.0.1.upstream/110.0.1upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 238 insertions, 0 deletions

diff --git a/dom/chrome-webidl/TelemetryStopwatch.webidl b/dom/chrome-webidl/TelemetryStopwatch.webidl
new file mode 100644
index 0000000000..92f8a0d630
--- /dev/null
+++ b/dom/chrome-webidl/TelemetryStopwatch.webidl
@@ -0,0 +1,238 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this file,
+ * You can obtain one at http://mozilla.org/MPL/2.0/.
+ */
+
+typedef DOMString HistogramID;
+typedef DOMString HistogramKey;
+
+[ChromeOnly, Exposed=Window]
+namespace TelemetryStopwatch {
+  /**
+   * Starts a timer associated with a telemetry histogram. The timer can be
+   * directly associated with a histogram, or with a pair of a histogram and
+   * an object.
+   *
+   * @param histogram - a string which must be a valid histogram name.
+   *
+   * @param obj - Optional parameter. If specified, the timer is
+   *              associated with this object, meaning that multiple
+   *              timers for the same histogram may be run
+   *              concurrently, as long as they are associated with
+   *              different objects.
+   * @param [options.inSeconds=false] - record elapsed time for this
+   *        histogram in seconds instead of milliseconds. Defaults to
+   *        false.
+   *
+   * @returns True if the timer was successfully started, false
+   *          otherwise. If a timer already exists, it can't be
+   *          started again, and the existing one will be cleared in
+   *          order to avoid measurements errors.
+   */
+  boolean start(HistogramID histogram, optional object? obj = null,
+                optional TelemetryStopwatchOptions options = {});
+
+  /**
+   * Returns whether a timer associated with a telemetry histogram is currently
+   * running. The timer can be directly associated with a histogram, or with a
+   * pair of a histogram and an object.
+   *
+   * @param histogram - a string which must be a valid histogram name.
+   *
+   * @param obj - Optional parameter. If specified, the timer is
+   *              associated with this object, meaning that multiple
+   *              timers for the same histogram may be run
+   *              concurrently, as long as they are associated with
+   *              different objects.
+   *
+   * @returns True if the timer exists and is currently running.
+   */
+  boolean running(HistogramID histogram, optional object? obj = null);
+
+  /**
+   * Deletes the timer associated with a telemetry histogram. The timer can be
+   * directly associated with a histogram, or with a pair of a histogram and
+   * an object. Important: Only use this method when a legitimate cancellation
+   * should be done.
+   *
+   * @param histogram - a string which must be a valid histogram name.
+   *
+   * @param obj - Optional parameter. If specified, the timer is
+   *              associated with this object, meaning that multiple
+   *              timers or a same histogram may be run concurrently,
+   *              as long as they are associated with different
+   *              objects.
+   *
+   * @returns True if the timer exist and it was cleared, False
+   *          otherwise.
+   */
+  boolean cancel(HistogramID histogram, optional object? obj = null);
+
+  /**
+   * Returns the elapsed time for a particular stopwatch. Primarily for
+   * debugging purposes. Must be called prior to finish.
+   *
+   * @param histogram - a string which must be a valid histogram name.
+   *                    if an invalid name is given, the function will
+   *                    throw.
+   *
+   * @param obj - Optional parameter which associates the histogram
+   *              timer with the given object.
+   *
+   * @param canceledOkay - Optional parameter which will suppress any
+   *                       warnings that normally fire when a stopwatch
+   *                       is finished after being cancelled. Defaults
+   *                       to false.
+   *
+   * @returns Time in milliseconds or -1 if the stopwatch was not
+   *          found.
+   */
+  long timeElapsed(HistogramID histogram,
+                   optional object? obj = null,
+                   optional boolean canceledOkay = false);
+
+  /**
+   * Stops the timer associated with the given histogram (and object),
+   * calculates the time delta between start and finish, and adds the value
+   * to the histogram.
+   *
+   * @param histogram - a string which must be a valid histogram name.
+   *
+   * @param obj - Optional parameter which associates the histogram
+   *              timer with the given object.
+   *
+   * @param canceledOkay - Optional parameter which will suppress any
+   *                       warnings that normally fire when a stopwatch
+   *                       is finished after being cancelled. Defaults
+   *                       to false.
+   *
+   * @returns True if the timer was succesfully stopped and the data
+   *          was added to the histogram, false otherwise.
+   */
+  boolean finish(HistogramID histogram,
+                 optional object? obj = null,
+                 optional boolean canceledOkay = false);
+
+  /**
+   * Starts a timer associated with a keyed telemetry histogram. The timer can
+   * be directly associated with a histogram and its key. Similarly to
+   * @see{TelemetryStopwatch.start} the histogram and its key can be associated
+   * with an object. Each key may have multiple associated objects and each
+   * object can be associated with multiple keys.
+   *
+   * @param histogram - a string which must be a valid histogram name.
+   *
+   * @param key - a string which must be a valid histgram key.
+   *
+   * @param obj - Optional parameter. If specified, the timer is
+   *              associated with this object, meaning that multiple
+   *              timers for the same histogram may be run
+   *              concurrently,as long as they are associated with
+   *              different objects.
+   * @param [options.inSeconds=false] - record elapsed time for this
+   *         histogram in seconds instead of milliseconds. Defaults to
+   *         false.
+   *
+   * @returns True if the timer was successfully started, false
+   *          otherwise. If a timer already exists, it can't be
+   *          started again, and the existing one will be cleared in
+   *          order to avoid measurements errors.
+   */
+  boolean startKeyed(HistogramID histogram, HistogramKey key,
+                     optional object? obj = null,
+                     optional TelemetryStopwatchOptions options = {});
+
+  /**
+   * Returns whether a timer associated with a telemetry histogram is currently
+   * running. Similarly to @see{TelemetryStopwatch.running} the timer and its
+   * key can be associated with an object. Each key may have multiple associated
+   * objects and each object can be associated with multiple keys.
+   *
+   * @param histogram - a string which must be a valid histogram name.
+   *
+   * @param key - a string which must be a valid histgram key.
+   *
+   * @param obj - Optional parameter. If specified, the timer is
+   *              associated with this object, meaning that multiple
+   *              timers for the same histogram may be run
+   *              concurrently, as long as they are associated with
+   *              different objects.
+   *
+   * @returns True if the timer exists and is currently running.
+   */
+  boolean runningKeyed(HistogramID histogram, HistogramKey key,
+                       optional object? obj = null);
+
+  /**
+   * Deletes the timer associated with a keyed histogram. Important: Only use
+   * this method when a legitimate cancellation should be done.
+   *
+   * @param histogram - a string which must be a valid histogram name.
+   *
+   * @param key - a string which must be a valid histgram key.
+   *
+   * @param obj - Optional parameter. If specified, the timer
+   *              associated with this object is deleted.
+   *
+   * @returns True if the timer exist and it was cleared, False
+   *          otherwise.
+   */
+  boolean cancelKeyed(HistogramID histogram, HistogramKey key,
+                      optional object? obj = null);
+
+  /**
+   * Returns the elapsed time for a particular stopwatch. Primarily for
+   * debugging purposes. Cannot be called after finish().
+   *
+   * @param histogram - a string which must be a valid histogram name.
+   *
+   * @param key - a string which must be a valid histgram key.
+   *
+   * @param obj - Optional parameter. If specified, the timer
+   *              associated with this object is used to calculate
+   *              the elapsed time.
+   *
+   * @returns Time in milliseconds or -1 if the stopwatch was not
+   *          found.
+   */
+  long timeElapsedKeyed(HistogramID histogram, HistogramKey key,
+                        optional object? obj = null,
+                        optional boolean canceledOkay = false);
+
+  /**
+   * Stops the timer associated with the given keyed histogram (and object),
+   * calculates the time delta between start and finish, and adds the value
+   * to the keyed histogram.
+   *
+   * @param histogram - a string which must be a valid histogram name.
+   *
+   * @param key - a string which must be a valid histgram key.
+   *
+   * @param obj - optional parameter which associates the histogram
+   *              timer with the given object.
+   *
+   * @param canceledOkay - Optional parameter which will suppress any
+   *                       warnings that normally fire when a stopwatch
+   *                       is finished after being cancelled. Defaults
+   *                       to false.
+   *
+   * @returns True if the timer was succesfully stopped and the data
+   *          was added to the histogram, false otherwise.
+   */
+  boolean finishKeyed(HistogramID histogram, HistogramKey key,
+                      optional object? obj = null,
+                      optional boolean canceledOkay = false);
+
+  /**
+   * Set the testing mode. Used by tests.
+   */
+  undefined setTestModeEnabled(optional boolean testing = true);
+};
+
+dictionary TelemetryStopwatchOptions {
+  /**
+   * If true, record elapsed time for this histogram in seconds instead of
+   * milliseconds.
+   */
+  boolean inSeconds = false;
+};