1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
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;
};
|
