Telemetry: extends Platform abstraction.

tools/telemetry/telemetry/platform.py

 # Copyright (c) 2012 The Chromium Authors. All rights reserved.
 # Use of this source code is governed by a BSD-style license that can be
 # found in the LICENSE file.
 
 class Platform(object):

[nduca, 2012/12/07 18:12:06]

By subclassing the platform, you override the doc strings. We want the
docstrings to be unchanged.

Two options
1. put the platform-specifc implementations into a class called PlatformBackend
that you construct Platform with, then each method here does
self._backend.GetRawDisplayFrameRate()
2. construct Platform with a browser_backend pointer and instead call right to
that
  self._backend.GetRawDisplayFrameRate()

[bulach, 2012/12/07 20:45:53]

ahn, thanks! I didn't know the the docstrings were overriden, I thought they
were inherited.. done.. 

   """The platform that the target browser is running on.
 
-  Provides a limited interface to obtain stats from the platform itself, where
-  possible.
+  Provides a limited interface to interact with the platform itself, where
+  possible. It's important to note that platforms may not provide a specific
+  API, so check with IsFooBar() for availability.
   """
+  def IsRawDisplayFrameRateSupported(self):
+    """Platforms may be able to collect GL surface stats."""
+    return False
 
-  def GetSurfaceCollector(self, trace_tag):
-    """Platforms may be able to collect GL surface stats."""
-    class StubSurfaceCollector(object):
-      def __init__(self, trace_tag):
-        pass
-      def __enter__(self):
-        pass
-      def __exit__(self, *args):
-        pass
+  def StartRawDisplayFrameRate(self, trace_tag):

[nduca, 2012/12/07 18:12:06]

Not clear whether you need a stop.

[bulach, 2012/12/07 20:45:53]

Done.

+    """Start collecting GL surface stats."""
+    raise NotImplementedError()
 
-    return StubSurfaceCollector(trace_tag)
+  def GetRawDisplayFrameRate(self):
+    """Prints GL surface stats."""

[nduca, 2012/12/07 18:12:06]

Not clear from the API if this can be called multiple times after startRaw, or
only once. 

[bulach, 2012/12/07 20:45:53]

Done.

+    raise NotImplementedError()
+
+  def SetFullPerformanceModeEnabled(self, enabled):
+    """Platforms may tweak their CPU governor, system status, etc."""

[nduca, 2012/12/07 18:12:06]

You might want to improve this docstring.  Something like

Most platforms can operate in a battery saving mode. While good for battery
life, this can cause confusing performance results. Turning full performance
mode on disables these features, which is useful for performance testing.

[bulach, 2012/12/07 20:45:53]

Done.

+    pass
+
+  def CanMonitorThermalThrottling(self):

[nduca, 2012/12/07 18:12:06]

Again, more docstring is good

Some fan-less computers go into a reduced performance mode when their heat
exceeds a certain threshold. Performance tests in particular should use this API
to detect if this has happened and interpret results accordingly.

[bulach, 2012/12/07 20:45:53]

Done.

+    """Platforms may be able to detect thermal throttling."""
+    return False
+
+  def StartMonitoringThermalThrottling(self):
+    """Start monitoring thermal throttling."""
+    raise NotImplementedError()
+
+  def StopMonitoringThermalThrottling(self):

[nduca, 2012/12/07 18:12:06]

Why start and stop? Why not just IsDeviceThermallyThrottled? You shouldn't log
inside this code, you should return a bool. The page runner should handle the
error.

[bulach, 2012/12/07 20:45:53]

Done.

+    """Stops monitoring thermal throttling."""
+    raise NotImplementedError()