summaryrefslogtreecommitdiffstats
path: root/dom/chrome-webidl/TelemetryStopwatch.webidl
diff options
context:
space:
mode:
Diffstat (limited to 'dom/chrome-webidl/TelemetryStopwatch.webidl')
-rw-r--r--dom/chrome-webidl/TelemetryStopwatch.webidl238
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;
+};