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
|
/* 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);
};
|
