content/public/renderer/plugin_instance_throttler.h

   1 // Copyright 2015 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef CONTENT_PUBLIC_RENDERER_PLUGIN_INSTANCE_THROTTLER_H_
   6 #define CONTENT_PUBLIC_RENDERER_PLUGIN_INSTANCE_THROTTLER_H_
   7
   8 #include "base/macros.h"
   9 #include "base/memory/scoped_ptr.h"
  10 #include "content/common/content_export.h"
  11
  12 namespace blink {
  13 class WebPlugin;
  14 struct WebPluginParams;
  15 }
  16
  17 class GURL;
  18 class SkBitmap;
  19
  20 namespace content {
  21
  22 // This class manages the metric collection, throttling, and unthrottling of a
  23 // single peripheral plugin instance. If the Power Saver feature is disabled,
  24 // the plugin instance will never actually be throttled, but still collects
  25 // user interaction metrics.
  26 //
  27 // The process for throttling a plugin is as follows:
  28 // 1) Attempt to find a representative keyframe to display as a placeholder for
  29 //    the plugin.
  30 // 2) a) If a representative keyframe is found, throttle the plugin at that
  31 //       keyframe.
  32 //    b) If a representative keyframe is not found, throttle the plugin after a
  33 //       certain period of time.
  34 //
  35 // The plugin will then be unthrottled by receiving a mouse click from the user.
  36 //
  37 // To choose a representative keyframe, we first wait for a certain number of
  38 // "interesting" frames to be displayed by the plugin. A frame is called
  39 // interesting if it meets some heuristic. After we have seen a certain number
  40 // of interesting frames, we throttle the plugin and use that frame as the
  41 // representative keyframe.
  42 class CONTENT_EXPORT PluginInstanceThrottler {
  43  public:
  44   // How the throttled power saver is unthrottled, if ever.
  45   // These numeric values are used in UMA logs; do not change them.
  46   enum PowerSaverUnthrottleMethod {
  47     UNTHROTTLE_METHOD_NEVER = 0,
  48     UNTHROTTLE_METHOD_BY_CLICK = 1,
  49     UNTHROTTLE_METHOD_BY_WHITELIST = 2,
  50     UNTHROTTLE_METHOD_BY_AUDIO = 3,
  51     UNTHROTTLE_METHOD_NUM_ITEMS
  52   };
  53
  54   class Observer {
  55    public:
  56     // Guaranteed to be called before the throttle is engaged.
  57     virtual void OnKeyframeExtracted(const SkBitmap* bitmap) {}
  58
  59     virtual void OnThrottleStateChange() {}
  60
  61     // Called when the plugin should be hidden due to a placeholder.
  62     virtual void OnHiddenForPlaceholder(bool hidden) {}
  63
  64     virtual void OnThrottlerDestroyed() {}
  65   };
  66
  67   static scoped_ptr<PluginInstanceThrottler> Create(bool power_saver_enabled);
  68
  69   static void RecordUnthrottleMethodMetric(PowerSaverUnthrottleMethod method);
  70
  71   virtual ~PluginInstanceThrottler() {}
  72
  73   virtual void AddObserver(Observer* observer) = 0;
  74   virtual void RemoveObserver(Observer* observer) = 0;
  75
  76   virtual bool IsThrottled() const = 0;
  77   virtual bool IsHiddenForPlaceholder() const = 0;
  78
  79   // Marks the plugin as essential. Unthrottles the plugin if already throttled.
  80   virtual void MarkPluginEssential(PowerSaverUnthrottleMethod method) = 0;
  81
  82   // Called by the placeholder when the plugin should temporarily be hidden.
  83   virtual void SetHiddenForPlaceholder(bool hidden) = 0;
  84
  85   virtual blink::WebPlugin* GetWebPlugin() const = 0;
  86
  87  protected:
  88   PluginInstanceThrottler() {}
  89
  90  private:
  91   DISALLOW_COPY_AND_ASSIGN(PluginInstanceThrottler);
  92 };
  93 }
  94
  95 #endif  // CONTENT_PUBLIC_RENDERER_PLUGIN_INSTANCE_THROTTLER_H_