diff options
Diffstat (limited to 'dom/chrome-webidl/TelemetryStopwatch.webidl')
| -rw-r--r-- | dom/chrome-webidl/TelemetryStopwatch.webidl | 238 |
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; +}; |