content/browser/frame_host/frame_tree.h

   1 // Copyright 2013 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_BROWSER_FRAME_HOST_FRAME_TREE_H_
   6 #define CONTENT_BROWSER_FRAME_HOST_FRAME_TREE_H_
   7
   8 #include <string>
   9
  10 #include "base/callback.h"
  11 #include "base/memory/scoped_ptr.h"
  12 #include "content/browser/frame_host/frame_tree_node.h"
  13 #include "content/common/content_export.h"
  14
  15 namespace content {
  16
  17 class FrameTreeNode;
  18 class Navigator;
  19 class RenderFrameHostDelegate;
  20 class RenderProcessHost;
  21 class RenderViewHostDelegate;
  22 class RenderViewHostImpl;
  23 class RenderFrameHostManager;
  24 class RenderWidgetHostDelegate;
  25
  26 // Represents the frame tree for a page. With the exception of the main frame,
  27 // all FrameTreeNodes will be created/deleted in response to frame attach and
  28 // detach events in the DOM.
  29 //
  30 // The main frame's FrameTreeNode is special in that it is reused. This allows
  31 // it to serve as an anchor for state that needs to persist across top-level
  32 // page navigations.
  33 //
  34 // TODO(ajwong): Move NavigationController ownership to the main frame
  35 // FrameTreeNode. Possibly expose access to it from here.
  36 //
  37 // This object is only used on the UI thread.
  38 class CONTENT_EXPORT FrameTree {
  39  public:
  40   // Each FrameTreeNode will default to using the given |navigator| for
  41   // navigation tasks in the frame.
  42   // A set of delegates are remembered here so that we can create
  43   // RenderFrameHostManagers.
  44   // TODO(creis): This set of delegates will change as we move things to
  45   // Navigator.
  46   FrameTree(Navigator* navigator,
  47             RenderFrameHostDelegate* render_frame_delegate,
  48             RenderViewHostDelegate* render_view_delegate,
  49             RenderWidgetHostDelegate* render_widget_delegate,
  50             RenderFrameHostManager::Delegate* manager_delegate);
  51   ~FrameTree();
  52
  53   FrameTreeNode* root() const { return root_.get(); }
  54
  55   // Returns the FrameTreeNode with the given |frame_tree_node_id| if it is part
  56   // of this FrameTree.
  57   FrameTreeNode* FindByID(int64 frame_tree_node_id);
  58
  59   // Returns the FrameTreeNode with the given renderer-specific |routing_id|.
  60   FrameTreeNode* FindByRoutingID(int process_id, int routing_id);
  61
  62   // Executes |on_node| on each node in the frame tree.  If |on_node| returns
  63   // false, terminates the iteration immediately. Returning false is useful
  64   // if |on_node| is just doing a search over the tree.  The iteration proceeds
  65   // top-down and visits a node before adding its children to the queue, making
  66   // it safe to remove children during the callback.
  67   void ForEach(const base::Callback<bool(FrameTreeNode*)>& on_node) const;
  68
  69   // Frame tree manipulation routines.
  70   // |process_id| is required to disambiguate |new_routing_id|, and it must
  71   // match the process of the |parent| node.  Otherwise this method returns
  72   // nullptr.  Passing MSG_ROUTING_NONE for |new_routing_id| will allocate a new
  73   // routing ID for the new frame.
  74   RenderFrameHostImpl* AddFrame(FrameTreeNode* parent,
  75                                 int process_id,
  76                                 int new_routing_id,
  77                                 const std::string& frame_name);
  78   void RemoveFrame(FrameTreeNode* child);
  79
  80   // This method walks the entire frame tree and creates a RenderFrameProxyHost
  81   // for the given |site_instance| in each node except the |source| one --
  82   // the source will have a RenderFrameHost. It assumes that no frame tree
  83   // nodes already have RenderFrameProxyHost for the given |site_instance|.
  84   void CreateProxiesForSiteInstance(
  85       FrameTreeNode* source,
  86       SiteInstance* site_instance);
  87
  88   // Clears process specific-state after a main frame process swap.
  89   // This destroys most of the frame tree but retains the root node so that
  90   // navigation state may be kept on it between process swaps. Used to
  91   // support bookkeeping for top-level navigations.
  92   // TODO(creis): Look into how we can remove the need for this method.
  93   void ResetForMainFrameSwap();
  94
  95   // Convenience accessor for the main frame's RenderFrameHostImpl.
  96   RenderFrameHostImpl* GetMainFrame() const;
  97
  98   // Returns the focused frame.
  99   FrameTreeNode* GetFocusedFrame();
 100
 101   // Sets the focused frame.
 102   void SetFocusedFrame(FrameTreeNode* node);
 103
 104   // Allows a client to listen for frame removal.  The listener should expect
 105   // to receive the RenderViewHostImpl containing the frame and the renderer-
 106   // specific frame routing ID of the removed frame.
 107   void SetFrameRemoveListener(
 108       const base::Callback<void(RenderFrameHost*)>& on_frame_removed);
 109
 110   // Creates a RenderViewHost for a new RenderFrameHost in the given
 111   // |site_instance|.  The RenderViewHost will have its Shutdown method called
 112   // when all of the RenderFrameHosts using it are deleted.
 113   RenderViewHostImpl* CreateRenderViewHost(SiteInstance* site_instance,
 114                                            int routing_id,
 115                                            int main_frame_routing_id,
 116                                            bool swapped_out,
 117                                            bool hidden);
 118
 119   // Returns the existing RenderViewHost for a new RenderFrameHost.
 120   // There should always be such a RenderViewHost, because the main frame
 121   // RenderFrameHost for each SiteInstance should be created before subframes.
 122   RenderViewHostImpl* GetRenderViewHost(SiteInstance* site_instance);
 123
 124   // Keeps track of which RenderFrameHosts are using each RenderViewHost.  When
 125   // the number drops to zero, we call Shutdown on the RenderViewHost.
 126   void RegisterRenderFrameHost(RenderFrameHostImpl* render_frame_host);
 127   void UnregisterRenderFrameHost(RenderFrameHostImpl* render_frame_host);
 128
 129   // This is only meant to be called by FrameTreeNode. Triggers calling
 130   // the listener installed by SetFrameRemoveListener.
 131   void FrameRemoved(FrameTreeNode* frame);
 132
 133   // Returns this FrameTree's total load progress.
 134   double GetLoadProgress();
 135
 136   // Resets the load progress on all nodes in this FrameTree.
 137   void ResetLoadProgress();
 138
 139   // Returns true if at least one of the nodes in this FrameTree is loading.
 140   bool IsLoading();
 141
 142  private:
 143   typedef base::hash_map<int, RenderViewHostImpl*> RenderViewHostMap;
 144   typedef std::multimap<int, RenderViewHostImpl*> RenderViewHostMultiMap;
 145
 146   // A variation to the public ForEach method with a difference that the subtree
 147   // starting at |skip_this_subtree| will not be recursed into.
 148   void ForEach(const base::Callback<bool(FrameTreeNode*)>& on_node,
 149                FrameTreeNode* skip_this_subtree) const;
 150
 151   // These delegates are installed into all the RenderViewHosts and
 152   // RenderFrameHosts that we create.
 153   RenderFrameHostDelegate* render_frame_delegate_;
 154   RenderViewHostDelegate* render_view_delegate_;
 155   RenderWidgetHostDelegate* render_widget_delegate_;
 156   RenderFrameHostManager::Delegate* manager_delegate_;
 157
 158   // Map of SiteInstance ID to a RenderViewHost.  This allows us to look up the
 159   // RenderViewHost for a given SiteInstance when creating RenderFrameHosts.
 160   // Combined with the refcount on RenderViewHost, this allows us to call
 161   // Shutdown on the RenderViewHost and remove it from the map when no more
 162   // RenderFrameHosts are using it.
 163   //
 164   // Must be declared before |root_| so that it is deleted afterward.  Otherwise
 165   // the map will be cleared before we delete the RenderFrameHosts in the tree.
 166   RenderViewHostMap render_view_host_map_;
 167
 168   // Map of SiteInstance ID to RenderViewHosts that are pending shutdown. The
 169   // renderers of these RVH are currently executing the unload event in
 170   // background. When the SwapOutACK is received, they will be deleted. In the
 171   // meantime, they are kept in this map, as they should not be reused (part of
 172   // their state is already gone away).
 173   RenderViewHostMultiMap render_view_host_pending_shutdown_map_;
 174
 175   scoped_ptr<FrameTreeNode> root_;
 176
 177   int64 focused_frame_tree_node_id_;
 178
 179   base::Callback<void(RenderFrameHost*)> on_frame_removed_;
 180
 181   DISALLOW_COPY_AND_ASSIGN(FrameTree);
 182 };
 183
 184 }  // namespace content
 185
 186 #endif  // CONTENT_BROWSER_FRAME_HOST_FRAME_TREE_H_