Source code
Revision control
Copy as Markdown
Other Tools
/* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* vim: set ts=8 sts=2 et sw=2 tw=80: */
/* 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
#ifndef mozilla_layers_CheckerboardEvent_h
#define mozilla_layers_CheckerboardEvent_h
#include "mozilla/DefineEnum.h"
#include "mozilla/Monitor.h"
#include "mozilla/TimeStamp.h"
#include <sstream>
#include "Units.h"
#include <vector>
namespace mozilla {
namespace layers {
/**
* This class records information relevant to one "checkerboard event", which is
* a contiguous set of frames where a given APZC was checkerboarding. The intent
* of this class is to record enough information that it can provide actionable
* steps to reduce the occurrence of checkerboarding. Furthermore, it records
* information about the severity of the checkerboarding so as to allow
* prioritizing the debugging of some checkerboarding events over others.
*/
class CheckerboardEvent final {
public:
// clang-format off
MOZ_DEFINE_ENUM_AT_CLASS_SCOPE(
RendertraceProperty, (
Page,
PaintedDisplayPort,
RequestedDisplayPort,
UserVisible
));
// clang-format on
static const char* sDescriptions[sRendertracePropertyCount];
static const char* sColors[sRendertracePropertyCount];
public:
explicit CheckerboardEvent(bool aRecordTrace);
/**
* Gets the "severity" of the checkerboard event. This doesn't have units,
* it's just useful for comparing two checkerboard events to see which one
* is worse, for some implementation-specific definition of "worse".
*/
uint32_t GetSeverity();
/**
* Gets the number of CSS pixels that were checkerboarded at the peak of the
* checkerboard event.
*/
uint32_t GetPeak();
/**
* Gets the length of the checkerboard event.
*/
TimeDuration GetDuration();
/**
* Gets the raw log of the checkerboard event. This can be called any time,
* although it really only makes sense to pull once the event is done, after
* RecordFrameInfo returns true.
*/
std::string GetLog();
/**
* Returns true iff this event is recording a detailed trace of the event.
* This is the argument passed in to the constructor.
*/
bool IsRecordingTrace();
/**
* Provide a new value for one of the rects that is tracked for
* checkerboard events.
*/
void UpdateRendertraceProperty(RendertraceProperty aProperty,
const CSSRect& aRect,
const std::string& aExtraInfo = std::string());
/**
* Provide the number of CSS pixels that are checkerboarded in a composite
* at the current time.
* @return true if the checkerboard event has completed. The caller should
* stop updating this object once this happens.
*/
bool RecordFrameInfo(uint32_t aCssPixelsCheckerboarded);
private:
/**
* Helper method to do stuff when checkeboarding starts.
*/
void StartEvent();
/**
* Helper method to do stuff when checkerboarding stops.
*/
void StopEvent();
/**
* Helper method to log a rendertrace property and its value to the
* rendertrace info buffer (mRendertraceInfo).
*/
void LogInfo(RendertraceProperty aProperty, const TimeStamp& aTimestamp,
const CSSRect& aRect, const std::string& aExtraInfo,
const MonitorAutoLock& aProofOfLock)
MOZ_REQUIRES(mRendertraceLock);
/**
* Helper struct that holds a single rendertrace property value.
*/
struct PropertyValue {
RendertraceProperty mProperty;
TimeStamp mTimeStamp;
CSSRect mRect;
std::string mExtraInfo;
bool operator<(const PropertyValue& aOther) const;
};
/**
* A circular buffer that stores the most recent BUFFER_SIZE values of a
* given property.
*/
class PropertyBuffer {
public:
PropertyBuffer();
/**
* Add a new value to the buffer, overwriting the oldest one if needed.
*/
void Update(RendertraceProperty aProperty, const CSSRect& aRect,
const std::string& aExtraInfo,
const MonitorAutoLock& aProofOfLock);
/**
* Dump the recorded values, oldest to newest, to the given vector, and
* remove them from this buffer.
*/
void Flush(std::vector<PropertyValue>& aOut,
const MonitorAutoLock& aProofOfLock);
private:
static const uint32_t BUFFER_SIZE = 5;
/**
* The index of the oldest value in the buffer. This is the next index
* that will be written to.
*/
uint32_t mIndex;
PropertyValue mValues[BUFFER_SIZE];
};
private:
/**
* If true, we should log the various properties during the checkerboard
* event. If false, we only need to record things we need for telemetry
* measures.
*/
const bool mRecordTrace;
/**
* A base time so that the other timestamps can be turned into durations.
*/
const TimeStamp mOriginTime;
/**
* Whether or not a checkerboard event is currently occurring.
*/
bool mCheckerboardingActive;
/**
* The start time of the checkerboard event.
*/
TimeStamp mStartTime;
/**
* The end time of the checkerboard event.
*/
TimeStamp mEndTime;
/**
* The sample time of the last frame recorded.
*/
TimeStamp mLastSampleTime;
/**
* The number of contiguous frames with checkerboard.
*/
uint32_t mFrameCount;
/**
* The total number of pixel-milliseconds of checkerboarding visible to
* the user during the checkerboarding event.
*/
uint64_t mTotalPixelMs;
/**
* The largest number of pixels of checkerboarding visible to the user
* during any one frame, during this checkerboarding event.
*/
uint32_t mPeakPixels;
/**
* Monitor that needs to be acquired before touching mBufferedProperties
* or mRendertraceInfo.
*/
mutable Monitor mRendertraceLock;
/**
* A circular buffer to store some properties. This is used before the
* checkerboarding actually starts, so that we have some data on what
* was happening before the checkerboarding started.
*/
PropertyBuffer mBufferedProperties[sRendertracePropertyCount] MOZ_GUARDED_BY(
mRendertraceLock);
/**
* The rendertrace info buffer that gives us info on what was happening
* during the checkerboard event.
*/
std::ostringstream mRendertraceInfo MOZ_GUARDED_BY(mRendertraceLock);
};
} // namespace layers
} // namespace mozilla
#endif // mozilla_layers_CheckerboardEvent_h