dom/chrome-webidl/TelemetryStopwatch.webidl

   1 /* This Source Code Form is subject to the terms of the Mozilla Public
   2  * License, v. 2.0. If a copy of the MPL was not distributed with this file,
   3  * You can obtain one at http://mozilla.org/MPL/2.0/.
   4  */
   5
   6 typedef DOMString HistogramID;
   7 typedef DOMString HistogramKey;
   8
   9 [ChromeOnly, Exposed=Window]
  10 namespace TelemetryStopwatch {
  11   /**
  12    * Starts a timer associated with a telemetry histogram. The timer can be
  13    * directly associated with a histogram, or with a pair of a histogram and
  14    * an object.
  15    *
  16    * @param histogram - a string which must be a valid histogram name.
  17    *
  18    * @param obj - Optional parameter. If specified, the timer is
  19    *              associated with this object, meaning that multiple
  20    *              timers for the same histogram may be run
  21    *              concurrently, as long as they are associated with
  22    *              different objects.
  23    * @param [options.inSeconds=false] - record elapsed time for this
  24    *        histogram in seconds instead of milliseconds. Defaults to
  25    *        false.
  26    *
  27    * @returns True if the timer was successfully started, false
  28    *          otherwise. If a timer already exists, it can't be
  29    *          started again, and the existing one will be cleared in
  30    *          order to avoid measurements errors.
  31    */
  32   boolean start(HistogramID histogram, optional object? obj = null,
  33                 optional TelemetryStopwatchOptions options = {});
  34
  35   /**
  36    * Returns whether a timer associated with a telemetry histogram is currently
  37    * running. The timer can be directly associated with a histogram, or with a
  38    * pair of a histogram and an object.
  39    *
  40    * @param histogram - a string which must be a valid histogram name.
  41    *
  42    * @param obj - Optional parameter. If specified, the timer is
  43    *              associated with this object, meaning that multiple
  44    *              timers for the same histogram may be run
  45    *              concurrently, as long as they are associated with
  46    *              different objects.
  47    *
  48    * @returns True if the timer exists and is currently running.
  49    */
  50   boolean running(HistogramID histogram, optional object? obj = null);
  51
  52   /**
  53    * Deletes the timer associated with a telemetry histogram. The timer can be
  54    * directly associated with a histogram, or with a pair of a histogram and
  55    * an object. Important: Only use this method when a legitimate cancellation
  56    * should be done.
  57    *
  58    * @param histogram - a string which must be a valid histogram name.
  59    *
  60    * @param obj - Optional parameter. If specified, the timer is
  61    *              associated with this object, meaning that multiple
  62    *              timers or a same histogram may be run concurrently,
  63    *              as long as they are associated with different
  64    *              objects.
  65    *
  66    * @returns True if the timer exist and it was cleared, False
  67    *          otherwise.
  68    */
  69   boolean cancel(HistogramID histogram, optional object? obj = null);
  70
  71   /**
  72    * Returns the elapsed time for a particular stopwatch. Primarily for
  73    * debugging purposes. Must be called prior to finish.
  74    *
  75    * @param histogram - a string which must be a valid histogram name.
  76    *                    if an invalid name is given, the function will
  77    *                    throw.
  78    *
  79    * @param obj - Optional parameter which associates the histogram
  80    *              timer with the given object.
  81    *
  82    * @param canceledOkay - Optional parameter which will suppress any
  83    *                       warnings that normally fire when a stopwatch
  84    *                       is finished after being cancelled. Defaults
  85    *                       to false.
  86    *
  87    * @returns Time in milliseconds or -1 if the stopwatch was not
  88    *          found.
  89    */
  90   long timeElapsed(HistogramID histogram,
  91                    optional object? obj = null,
  92                    optional boolean canceledOkay = false);
  93
  94   /**
  95    * Stops the timer associated with the given histogram (and object),
  96    * calculates the time delta between start and finish, and adds the value
  97    * to the histogram.
  98    *
  99    * @param histogram - a string which must be a valid histogram name.
 100    *
 101    * @param obj - Optional parameter which associates the histogram
 102    *              timer with the given object.
 103    *
 104    * @param canceledOkay - Optional parameter which will suppress any
 105    *                       warnings that normally fire when a stopwatch
 106    *                       is finished after being cancelled. Defaults
 107    *                       to false.
 108    *
 109    * @returns True if the timer was succesfully stopped and the data
 110    *          was added to the histogram, false otherwise.
 111    */
 112   boolean finish(HistogramID histogram,
 113                  optional object? obj = null,
 114                  optional boolean canceledOkay = false);
 115
 116   /**
 117    * Starts a timer associated with a keyed telemetry histogram. The timer can
 118    * be directly associated with a histogram and its key. Similarly to
 119    * @see{TelemetryStopwatch.start} the histogram and its key can be associated
 120    * with an object. Each key may have multiple associated objects and each
 121    * object can be associated with multiple keys.
 122    *
 123    * @param histogram - a string which must be a valid histogram name.
 124    *
 125    * @param key - a string which must be a valid histgram key.
 126    *
 127    * @param obj - Optional parameter. If specified, the timer is
 128    *              associated with this object, meaning that multiple
 129    *              timers for the same histogram may be run
 130    *              concurrently,as long as they are associated with
 131    *              different objects.
 132    * @param [options.inSeconds=false] - record elapsed time for this
 133    *         histogram in seconds instead of milliseconds. Defaults to
 134    *         false.
 135    *
 136    * @returns True if the timer was successfully started, false
 137    *          otherwise. If a timer already exists, it can't be
 138    *          started again, and the existing one will be cleared in
 139    *          order to avoid measurements errors.
 140    */
 141   boolean startKeyed(HistogramID histogram, HistogramKey key,
 142                      optional object? obj = null,
 143                      optional TelemetryStopwatchOptions options = {});
 144
 145   /**
 146    * Returns whether a timer associated with a telemetry histogram is currently
 147    * running. Similarly to @see{TelemetryStopwatch.running} the timer and its
 148    * key can be associated with an object. Each key may have multiple associated
 149    * objects and each object can be associated with multiple keys.
 150    *
 151    * @param histogram - a string which must be a valid histogram name.
 152    *
 153    * @param key - a string which must be a valid histgram key.
 154    *
 155    * @param obj - Optional parameter. If specified, the timer is
 156    *              associated with this object, meaning that multiple
 157    *              timers for the same histogram may be run
 158    *              concurrently, as long as they are associated with
 159    *              different objects.
 160    *
 161    * @returns True if the timer exists and is currently running.
 162    */
 163   boolean runningKeyed(HistogramID histogram, HistogramKey key,
 164                        optional object? obj = null);
 165
 166   /**
 167    * Deletes the timer associated with a keyed histogram. Important: Only use
 168    * this method when a legitimate cancellation should be done.
 169    *
 170    * @param histogram - a string which must be a valid histogram name.
 171    *
 172    * @param key - a string which must be a valid histgram key.
 173    *
 174    * @param obj - Optional parameter. If specified, the timer
 175    *              associated with this object is deleted.
 176    *
 177    * @returns True if the timer exist and it was cleared, False
 178    *          otherwise.
 179    */
 180   boolean cancelKeyed(HistogramID histogram, HistogramKey key,
 181                       optional object? obj = null);
 182
 183   /**
 184    * Returns the elapsed time for a particular stopwatch. Primarily for
 185    * debugging purposes. Cannot be called after finish().
 186    *
 187    * @param histogram - a string which must be a valid histogram name.
 188    *
 189    * @param key - a string which must be a valid histgram key.
 190    *
 191    * @param obj - Optional parameter. If specified, the timer
 192    *              associated with this object is used to calculate
 193    *              the elapsed time.
 194    *
 195    * @returns Time in milliseconds or -1 if the stopwatch was not
 196    *          found.
 197    */
 198   long timeElapsedKeyed(HistogramID histogram, HistogramKey key,
 199                         optional object? obj = null,
 200                         optional boolean canceledOkay = false);
 201
 202   /**
 203    * Stops the timer associated with the given keyed histogram (and object),
 204    * calculates the time delta between start and finish, and adds the value
 205    * to the keyed histogram.
 206    *
 207    * @param histogram - a string which must be a valid histogram name.
 208    *
 209    * @param key - a string which must be a valid histgram key.
 210    *
 211    * @param obj - optional parameter which associates the histogram
 212    *              timer with the given object.
 213    *
 214    * @param canceledOkay - Optional parameter which will suppress any
 215    *                       warnings that normally fire when a stopwatch
 216    *                       is finished after being cancelled. Defaults
 217    *                       to false.
 218    *
 219    * @returns True if the timer was succesfully stopped and the data
 220    *          was added to the histogram, false otherwise.
 221    */
 222   boolean finishKeyed(HistogramID histogram, HistogramKey key,
 223                       optional object? obj = null,
 224                       optional boolean canceledOkay = false);
 225
 226   /**
 227    * Set the testing mode. Used by tests.
 228    */
 229   undefined setTestModeEnabled(optional boolean testing = true);
 230 };
 231
 232 dictionary TelemetryStopwatchOptions {
 233   /**
 234    * If true, record elapsed time for this histogram in seconds instead of
 235    * milliseconds.
 236    */
 237   boolean inSeconds = false;
 238 };