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/.
6 typedef DOMString HistogramID;
7 typedef DOMString HistogramKey;
9 [ChromeOnly, Exposed=Window]
10 namespace TelemetryStopwatch {
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
16 * @param histogram - a string which must be a valid histogram name.
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
23 * @param [options.inSeconds=false] - record elapsed time for this
24 * histogram in seconds instead of milliseconds. Defaults to
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.
32 boolean start(HistogramID histogram, optional object? obj = null,
33 optional TelemetryStopwatchOptions options = {});
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.
40 * @param histogram - a string which must be a valid histogram name.
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
48 * @returns True if the timer exists and is currently running.
50 boolean running(HistogramID histogram, optional object? obj = null);
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
58 * @param histogram - a string which must be a valid histogram name.
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
66 * @returns True if the timer exist and it was cleared, False
69 boolean cancel(HistogramID histogram, optional object? obj = null);
72 * Returns the elapsed time for a particular stopwatch. Primarily for
73 * debugging purposes. Must be called prior to finish.
75 * @param histogram - a string which must be a valid histogram name.
76 * if an invalid name is given, the function will
79 * @param obj - Optional parameter which associates the histogram
80 * timer with the given object.
82 * @param canceledOkay - Optional parameter which will suppress any
83 * warnings that normally fire when a stopwatch
84 * is finished after being cancelled. Defaults
87 * @returns Time in milliseconds or -1 if the stopwatch was not
90 long timeElapsed(HistogramID histogram,
91 optional object? obj = null,
92 optional boolean canceledOkay = false);
95 * Stops the timer associated with the given histogram (and object),
96 * calculates the time delta between start and finish, and adds the value
99 * @param histogram - a string which must be a valid histogram name.
101 * @param obj - Optional parameter which associates the histogram
102 * timer with the given object.
104 * @param canceledOkay - Optional parameter which will suppress any
105 * warnings that normally fire when a stopwatch
106 * is finished after being cancelled. Defaults
109 * @returns True if the timer was succesfully stopped and the data
110 * was added to the histogram, false otherwise.
112 boolean finish(HistogramID histogram,
113 optional object? obj = null,
114 optional boolean canceledOkay = false);
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.
123 * @param histogram - a string which must be a valid histogram name.
125 * @param key - a string which must be a valid histgram key.
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
132 * @param [options.inSeconds=false] - record elapsed time for this
133 * histogram in seconds instead of milliseconds. Defaults to
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.
141 boolean startKeyed(HistogramID histogram, HistogramKey key,
142 optional object? obj = null,
143 optional TelemetryStopwatchOptions options = {});
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.
151 * @param histogram - a string which must be a valid histogram name.
153 * @param key - a string which must be a valid histgram key.
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
161 * @returns True if the timer exists and is currently running.
163 boolean runningKeyed(HistogramID histogram, HistogramKey key,
164 optional object? obj = null);
167 * Deletes the timer associated with a keyed histogram. Important: Only use
168 * this method when a legitimate cancellation should be done.
170 * @param histogram - a string which must be a valid histogram name.
172 * @param key - a string which must be a valid histgram key.
174 * @param obj - Optional parameter. If specified, the timer
175 * associated with this object is deleted.
177 * @returns True if the timer exist and it was cleared, False
180 boolean cancelKeyed(HistogramID histogram, HistogramKey key,
181 optional object? obj = null);
184 * Returns the elapsed time for a particular stopwatch. Primarily for
185 * debugging purposes. Cannot be called after finish().
187 * @param histogram - a string which must be a valid histogram name.
189 * @param key - a string which must be a valid histgram key.
191 * @param obj - Optional parameter. If specified, the timer
192 * associated with this object is used to calculate
195 * @returns Time in milliseconds or -1 if the stopwatch was not
198 long timeElapsedKeyed(HistogramID histogram, HistogramKey key,
199 optional object? obj = null,
200 optional boolean canceledOkay = false);
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.
207 * @param histogram - a string which must be a valid histogram name.
209 * @param key - a string which must be a valid histgram key.
211 * @param obj - optional parameter which associates the histogram
212 * timer with the given object.
214 * @param canceledOkay - Optional parameter which will suppress any
215 * warnings that normally fire when a stopwatch
216 * is finished after being cancelled. Defaults
219 * @returns True if the timer was succesfully stopped and the data
220 * was added to the histogram, false otherwise.
222 boolean finishKeyed(HistogramID histogram, HistogramKey key,
223 optional object? obj = null,
224 optional boolean canceledOkay = false);
227 * Set the testing mode. Used by tests.
229 void setTestModeEnabled(optional boolean testing = true);
232 dictionary TelemetryStopwatchOptions {
234 * If true, record elapsed time for this histogram in seconds instead of
237 boolean inSeconds = false;