зеркало из https://github.com/mozilla/gecko-dev.git
239 строки
9.6 KiB
Plaintext
239 строки
9.6 KiB
Plaintext
/* 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.
|
|
*/
|
|
void setTestModeEnabled(optional boolean testing = true);
|
|
};
|
|
|
|
dictionary TelemetryStopwatchOptions {
|
|
/**
|
|
* If true, record elapsed time for this histogram in seconds instead of
|
|
* milliseconds.
|
|
*/
|
|
boolean inSeconds = false;
|
|
};
|