Line data Source code
1 : /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
2 : /* This Source Code Form is subject to the terms of the Mozilla Public
3 : * License, v. 2.0. If a copy of the MPL was not distributed with this
4 : * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
5 :
6 : #ifndef mozilla_layers_CheckerboardEvent_h
7 : #define mozilla_layers_CheckerboardEvent_h
8 :
9 : #include "mozilla/DefineEnum.h"
10 : #include "mozilla/Monitor.h"
11 : #include "mozilla/TimeStamp.h"
12 : #include <sstream>
13 : #include "Units.h"
14 : #include <vector>
15 :
16 : namespace mozilla {
17 : namespace layers {
18 :
19 : /**
20 : * This class records information relevant to one "checkerboard event", which is
21 : * a contiguous set of frames where a given APZC was checkerboarding. The intent
22 : * of this class is to record enough information that it can provide actionable
23 : * steps to reduce the occurrence of checkerboarding. Furthermore, it records
24 : * information about the severity of the checkerboarding so as to allow
25 : * prioritizing the debugging of some checkerboarding events over others.
26 : */
27 0 : class CheckerboardEvent {
28 : public:
29 : MOZ_DEFINE_ENUM_AT_CLASS_SCOPE(
30 : RendertraceProperty, (
31 : Page,
32 : PaintedCriticalDisplayPort,
33 : PaintedDisplayPort,
34 : RequestedDisplayPort,
35 : UserVisible
36 : ));
37 :
38 : static const char* sDescriptions[sRendertracePropertyCount];
39 : static const char* sColors[sRendertracePropertyCount];
40 :
41 : public:
42 : explicit CheckerboardEvent(bool aRecordTrace);
43 :
44 : /**
45 : * Gets the "severity" of the checkerboard event. This doesn't have units,
46 : * it's just useful for comparing two checkerboard events to see which one
47 : * is worse, for some implementation-specific definition of "worse".
48 : */
49 : uint32_t GetSeverity();
50 :
51 : /**
52 : * Gets the number of CSS pixels that were checkerboarded at the peak of the
53 : * checkerboard event.
54 : */
55 : uint32_t GetPeak();
56 :
57 : /**
58 : * Gets the length of the checkerboard event.
59 : */
60 : TimeDuration GetDuration();
61 :
62 : /**
63 : * Gets the raw log of the checkerboard event. This can be called any time,
64 : * although it really only makes sense to pull once the event is done, after
65 : * RecordFrameInfo returns true.
66 : */
67 : std::string GetLog();
68 :
69 : /**
70 : * Returns true iff this event is recording a detailed trace of the event.
71 : * This is the argument passed in to the constructor.
72 : */
73 : bool IsRecordingTrace();
74 :
75 : /**
76 : * Provide a new value for one of the rects that is tracked for
77 : * checkerboard events.
78 : */
79 : void UpdateRendertraceProperty(RendertraceProperty aProperty,
80 : const CSSRect& aRect,
81 : const std::string& aExtraInfo = std::string());
82 :
83 : /**
84 : * Provide the number of CSS pixels that are checkerboarded in a composite
85 : * at the current time.
86 : * @return true if the checkerboard event has completed. The caller should
87 : * stop updating this object once this happens.
88 : */
89 : bool RecordFrameInfo(uint32_t aCssPixelsCheckerboarded);
90 :
91 : private:
92 : /**
93 : * Helper method to do stuff when checkeboarding starts.
94 : */
95 : void StartEvent();
96 : /**
97 : * Helper method to do stuff when checkerboarding stops.
98 : */
99 : void StopEvent();
100 :
101 : /**
102 : * Helper method to log a rendertrace property and its value to the
103 : * rendertrace info buffer (mRendertraceInfo).
104 : */
105 : void LogInfo(RendertraceProperty aProperty,
106 : const TimeStamp& aTimestamp,
107 : const CSSRect& aRect,
108 : const std::string& aExtraInfo,
109 : const MonitorAutoLock& aProofOfLock);
110 :
111 : /**
112 : * Helper struct that holds a single rendertrace property value.
113 : */
114 154 : struct PropertyValue
115 : {
116 : RendertraceProperty mProperty;
117 : TimeStamp mTimeStamp;
118 : CSSRect mRect;
119 : std::string mExtraInfo;
120 :
121 : bool operator<(const PropertyValue& aOther) const;
122 : };
123 :
124 : /**
125 : * A circular buffer that stores the most recent BUFFER_SIZE values of a
126 : * given property.
127 : */
128 0 : class PropertyBuffer
129 : {
130 : public:
131 : PropertyBuffer();
132 : /**
133 : * Add a new value to the buffer, overwriting the oldest one if needed.
134 : */
135 : void Update(RendertraceProperty aProperty, const CSSRect& aRect,
136 : const std::string& aExtraInfo,
137 : const MonitorAutoLock& aProofOfLock);
138 : /**
139 : * Dump the recorded values, oldest to newest, to the given vector, and
140 : * remove them from this buffer.
141 : */
142 : void Flush(std::vector<PropertyValue>& aOut,
143 : const MonitorAutoLock& aProofOfLock);
144 :
145 : private:
146 : static const uint32_t BUFFER_SIZE = 5;
147 :
148 : /**
149 : * The index of the oldest value in the buffer. This is the next index
150 : * that will be written to.
151 : */
152 : uint32_t mIndex;
153 : PropertyValue mValues[BUFFER_SIZE];
154 : };
155 :
156 : private:
157 : /**
158 : * If true, we should log the various properties during the checkerboard
159 : * event. If false, we only need to record things we need for telemetry
160 : * measures.
161 : */
162 : const bool mRecordTrace;
163 : /**
164 : * A base time so that the other timestamps can be turned into durations.
165 : */
166 : const TimeStamp mOriginTime;
167 : /**
168 : * Whether or not a checkerboard event is currently occurring.
169 : */
170 : bool mCheckerboardingActive;
171 :
172 : /**
173 : * The start time of the checkerboard event.
174 : */
175 : TimeStamp mStartTime;
176 : /**
177 : * The end time of the checkerboard event.
178 : */
179 : TimeStamp mEndTime;
180 : /**
181 : * The sample time of the last frame recorded.
182 : */
183 : TimeStamp mLastSampleTime;
184 : /**
185 : * The number of contiguous frames with checkerboard.
186 : */
187 : uint32_t mFrameCount;
188 : /**
189 : * The total number of pixel-milliseconds of checkerboarding visible to
190 : * the user during the checkerboarding event.
191 : */
192 : uint64_t mTotalPixelMs;
193 : /**
194 : * The largest number of pixels of checkerboarding visible to the user
195 : * during any one frame, during this checkerboarding event.
196 : */
197 : uint32_t mPeakPixels;
198 :
199 : /**
200 : * Monitor that needs to be acquired before touching mBufferedProperties
201 : * or mRendertraceInfo.
202 : */
203 : mutable Monitor mRendertraceLock;
204 : /**
205 : * A circular buffer to store some properties. This is used before the
206 : * checkerboarding actually starts, so that we have some data on what
207 : * was happening before the checkerboarding started.
208 : */
209 : PropertyBuffer mBufferedProperties[sRendertracePropertyCount];
210 : /**
211 : * The rendertrace info buffer that gives us info on what was happening
212 : * during the checkerboard event.
213 : */
214 : std::ostringstream mRendertraceInfo;
215 : };
216 :
217 : } // namespace layers
218 : } // namespace mozilla
219 :
220 : #endif // mozilla_layers_CheckerboardEvent_h
|
