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 [ChromeOnly, Exposed=Window]
7 namespace UserInteraction {
9 * Starts a timer associated with a UserInteraction ID. The timer can be
10 * directly associated with a UserInteraction ID, or with a pair of a
11 * UserInteraction ID and an object.
13 * @param id - the interaction being recorded, as
14 * declared in UserInteractions.yaml. This is also the annotation
15 * key that will be set in the BHR hang report if a hang occurs
16 * before the UserInteraction is finished.
18 * @param value - a value to be set on the key in the event
19 * that a hang occurs when the timer is running. This value is limited
20 * to 50 characters to avoid abuse, and if the value exceeds that limit
21 * then no timer is started, an error is printed, and this function returns
24 * @param obj - Optional parameter. If specified, the timer is
25 * associated with this object, meaning that multiple timers for the
26 * same annotation key may be run concurrently, as long as they are
27 * associated with different objects.
29 * @returns True if the timer was successfully started, false otherwise.
30 * If a timer already exists, it will be overwritten, and the new timer
31 * will include a "(clobbered)" suffix in any BHR annotations that get
34 boolean start(DOMString id,
36 optional object? obj = null);
39 * Updates an already-running timer associated with a UserInteraction ID
40 * (and object) with a new value string.
42 * @param id - the interaction being recorded, as
43 * declared in UserInteractions.yaml. This is also the annotation
44 * key that will be set in the BHR hang report if a hang occurs
45 * before the UserInteraction is finished.
47 * @param value - a new value to be set on the key in the event
48 * that a hang occurs when the timer is running. This value is limited
49 * to 50 characters to avoid abuse.
51 * @param obj - Optional parameter. If specified, the timer is
52 * associated with this object, meaning that multiple timers for the
53 * same annotation key may be run concurrently, as long as they are
54 * associated with different objects.
56 * @returns True if the timer was successfully updated, false
59 boolean update(DOMString id,
61 optional object? obj = null);
64 * Cancels the timer associated with the given UserInteraction ID
65 * (and object) and does not add the profiler marker for it.
67 * @param id - the interaction being recorded, as
68 * declared in UserInteractions.yaml.
70 * @param obj - Optional parameter which associates the
71 * timer with the given object.
73 * @returns True if the timer was successfully stopped.
75 boolean cancel(DOMString id, optional object? obj = null);
78 * Returns whether a UserInteraction timer is currently running.
80 * @param id - the ID of the interaction to check, as declared in
81 * UserInteractions.yaml.
83 * @param obj - Optional parameter which checks for a timer associated
84 * with this particular object. If you're checking for a running timer
85 * that was started with an object, you'll need to pass in that same
86 * object here to check its running state.
88 * @returns True if the timer exists and is currently running.
90 boolean running(DOMString id, optional object? obj = null);
93 * Stops the timer associated with the given UserInteraction ID
94 * (and object), calculates the time delta between start and finish,
95 * and adds a profiler marker with that time range.
97 * @param id - the interaction being recorded, as
98 * declared in UserInteractions.yaml.
100 * @param obj - Optional parameter which associates the
101 * timer with the given object.
103 * @param additionalText - Optional parameter with includes additional
104 * text in the profiler marker. This text is not included in the hang
107 * @returns True if the timer was successfully stopped and the data
108 * was added to the profile.
110 boolean finish(DOMString id,
111 optional object? obj = null,
112 optional UTF8String additionalText);