mirror of
https://github.com/mozilla/gecko-dev.git
synced 2024-12-12 00:50:40 +00:00
afeb4e8d2e
Depends on D93589 Differential Revision: https://phabricator.services.mozilla.com/D93590
114 lines
4.3 KiB
Plaintext
114 lines
4.3 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/.
|
|
*/
|
|
|
|
[ChromeOnly, Exposed=Window]
|
|
namespace UserInteraction {
|
|
/**
|
|
* Starts a timer associated with a UserInteraction ID. The timer can be
|
|
* directly associated with a UserInteraction ID, or with a pair of a
|
|
* UserInteraction ID and an object.
|
|
*
|
|
* @param id - the interaction being recorded, as
|
|
* declared in UserInteractions.yaml. This is also the annotation
|
|
* key that will be set in the BHR hang report if a hang occurs
|
|
* before the UserInteraction is finished.
|
|
*
|
|
* @param value - a value to be set on the key in the event
|
|
* that a hang occurs when the timer is running. This value is limited
|
|
* to 50 characters to avoid abuse, and if the value exceeds that limit
|
|
* then no timer is started, an error is printed, and this function returns
|
|
* false.
|
|
*
|
|
* @param obj - Optional parameter. If specified, the timer is
|
|
* associated with this object, meaning that multiple timers for the
|
|
* same annotation key may be run concurrently, as long as they are
|
|
* associated with different objects.
|
|
*
|
|
* @returns True if the timer was successfully started, false otherwise.
|
|
* If a timer already exists, it will be overwritten, and the new timer
|
|
* will include a "(clobbered)" suffix in any BHR annotations that get
|
|
* created.
|
|
*/
|
|
boolean start(DOMString id,
|
|
UTF8String value,
|
|
optional object? obj = null);
|
|
|
|
/**
|
|
* Updates an already-running timer associated with a UserInteraction ID
|
|
* (and object) with a new value string.
|
|
*
|
|
* @param id - the interaction being recorded, as
|
|
* declared in UserInteractions.yaml. This is also the annotation
|
|
* key that will be set in the BHR hang report if a hang occurs
|
|
* before the UserInteraction is finished.
|
|
*
|
|
* @param value - a new value to be set on the key in the event
|
|
* that a hang occurs when the timer is running. This value is limited
|
|
* to 50 characters to avoid abuse.
|
|
*
|
|
* @param obj - Optional parameter. If specified, the timer is
|
|
* associated with this object, meaning that multiple timers for the
|
|
* same annotation key may be run concurrently, as long as they are
|
|
* associated with different objects.
|
|
*
|
|
* @returns True if the timer was successfully updated, false
|
|
* otherwise.
|
|
*/
|
|
boolean update(DOMString id,
|
|
UTF8String value,
|
|
optional object? obj = null);
|
|
|
|
/**
|
|
* Cancels the timer associated with the given UserInteraction ID
|
|
* (and object) and does not add the profiler marker for it.
|
|
*
|
|
* @param id - the interaction being recorded, as
|
|
* declared in UserInteractions.yaml.
|
|
*
|
|
* @param obj - Optional parameter which associates the
|
|
* timer with the given object.
|
|
*
|
|
* @returns True if the timer was successfully stopped.
|
|
*/
|
|
boolean cancel(DOMString id, optional object? obj = null);
|
|
|
|
/**
|
|
* Returns whether a UserInteraction timer is currently running.
|
|
*
|
|
* @param id - the ID of the interaction to check, as declared in
|
|
* UserInteractions.yaml.
|
|
*
|
|
* @param obj - Optional parameter which checks for a timer associated
|
|
* with this particular object. If you're checking for a running timer
|
|
* that was started with an object, you'll need to pass in that same
|
|
* object here to check its running state.
|
|
*
|
|
* @returns True if the timer exists and is currently running.
|
|
*/
|
|
boolean running(DOMString id, optional object? obj = null);
|
|
|
|
/**
|
|
* Stops the timer associated with the given UserInteraction ID
|
|
* (and object), calculates the time delta between start and finish,
|
|
* and adds a profiler marker with that time range.
|
|
*
|
|
* @param id - the interaction being recorded, as
|
|
* declared in UserInteractions.yaml.
|
|
*
|
|
* @param obj - Optional parameter which associates the
|
|
* timer with the given object.
|
|
*
|
|
* @param additionalText - Optional parameter with includes additional
|
|
* text in the profiler marker. This text is not included in the hang
|
|
* annotation.
|
|
*
|
|
* @returns True if the timer was successfully stopped and the data
|
|
* was added to the profile.
|
|
*/
|
|
boolean finish(DOMString id,
|
|
optional object? obj = null,
|
|
optional UTF8String additionalText);
|
|
};
|