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(int 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   // Returns the first frame in this tree with the given |name|, or the main
  63   // frame if |name| is empty.
  64   // Note that this does NOT support pseudo-names like _self, _top, and _blank,
  65   // nor searching other FrameTrees (unlike blink::WebView::findFrameByName).
  66   FrameTreeNode* FindByName(const std::string& name);
  67
  68   // Executes |on_node| on each node in the frame tree.  If |on_node| returns
  69   // false, terminates the iteration immediately. Returning false is useful
  70   // if |on_node| is just doing a search over the tree.  The iteration proceeds
  71   // top-down and visits a node before adding its children to the queue, making
  72   // it safe to remove children during the callback.
  73   void ForEach(const base::Callback<bool(FrameTreeNode*)>& on_node) const;
  74
  75   // Frame tree manipulation routines.
  76   // |process_id| is required to disambiguate |new_routing_id|, and it must
  77   // match the process of the |parent| node.  Otherwise this method returns
  78   // nullptr.  Passing MSG_ROUTING_NONE for |new_routing_id| will allocate a new
  79   // routing ID for the new frame.
  80   RenderFrameHostImpl* AddFrame(FrameTreeNode* parent,
  81                                 int process_id,
  82                                 int new_routing_id,
  83                                 blink::WebTreeScopeType scope,
  84                                 const std::string& frame_name,
  85                                 blink::WebSandboxFlags sandbox_flags);
  86   void RemoveFrame(FrameTreeNode* child);
  87
  88   // This method walks the entire frame tree and creates a RenderFrameProxyHost
  89   // for the given |site_instance| in each node except the |source| one --
  90   // the source will have a RenderFrameHost.  |source| may be null if there is
  91   // no node navigating in this frame tree (such as when this is called
  92   // for an opener's frame tree), in which case no nodes are skipped for
  93   // RenderFrameProxyHost creation.
  94   void CreateProxiesForSiteInstance(FrameTreeNode* source,
  95                                     SiteInstance* site_instance);
  96
  97   // Convenience accessor for the main frame's RenderFrameHostImpl.
  98   RenderFrameHostImpl* GetMainFrame() const;
  99
 100   // Returns the focused frame.
 101   FrameTreeNode* GetFocusedFrame();
 102
 103   // Sets the focused frame.
 104   void SetFocusedFrame(FrameTreeNode* node);
 105
 106   // Allows a client to listen for frame removal.  The listener should expect
 107   // to receive the RenderViewHostImpl containing the frame and the renderer-
 108   // specific frame routing ID of the removed frame.
 109   void SetFrameRemoveListener(
 110       const base::Callback<void(RenderFrameHost*)>& on_frame_removed);
 111
 112   // Creates a RenderViewHost for a new RenderFrameHost in the given
 113   // |site_instance|.  The RenderViewHost will have its Shutdown method called
 114   // when all of the RenderFrameHosts using it are deleted.
 115   RenderViewHostImpl* CreateRenderViewHost(SiteInstance* site_instance,
 116                                            int32 routing_id,
 117                                            int32 main_frame_routing_id,
 118                                            bool swapped_out,
 119                                            bool hidden);
 120
 121   // Returns the existing RenderViewHost for a new RenderFrameHost.
 122   // There should always be such a RenderViewHost, because the main frame
 123   // RenderFrameHost for each SiteInstance should be created before subframes.
 124   RenderViewHostImpl* GetRenderViewHost(SiteInstance* site_instance);
 125
 126   // Keeps track of which RenderFrameHosts and RenderFrameProxyHosts are using
 127   // each RenderViewHost.  When the number drops to zero, we call Shutdown on
 128   // the RenderViewHost.
 129   void AddRenderViewHostRef(RenderViewHostImpl* render_view_host);
 130   void ReleaseRenderViewHostRef(RenderViewHostImpl* render_view_host);
 131
 132   // This is only meant to be called by FrameTreeNode. Triggers calling
 133   // the listener installed by SetFrameRemoveListener.
 134   void FrameRemoved(FrameTreeNode* frame);
 135
 136   // Updates the overall load progress and notifies the WebContents.
 137   void UpdateLoadProgress();
 138
 139   // Returns this FrameTree's total load progress.
 140   double load_progress() { return load_progress_; }
 141
 142   // Resets the load progress on all nodes in this FrameTree.
 143   void ResetLoadProgress();
 144
 145   // Returns true if at least one of the nodes in this FrameTree is loading.
 146   bool IsLoading();
 147
 148  private:
 149   FRIEND_TEST_ALL_PREFIXES(RenderFrameHostImplBrowserTest, RemoveFocusedFrame);
 150   typedef base::hash_map<int, RenderViewHostImpl*> RenderViewHostMap;
 151   typedef std::multimap<int, RenderViewHostImpl*> RenderViewHostMultiMap;
 152
 153   // A variation to the public ForEach method with a difference that the subtree
 154   // starting at |skip_this_subtree| will not be recursed into.
 155   void ForEach(const base::Callback<bool(FrameTreeNode*)>& on_node,
 156                FrameTreeNode* skip_this_subtree) const;
 157
 158   // These delegates are installed into all the RenderViewHosts and
 159   // RenderFrameHosts that we create.
 160   RenderFrameHostDelegate* render_frame_delegate_;
 161   RenderViewHostDelegate* render_view_delegate_;
 162   RenderWidgetHostDelegate* render_widget_delegate_;
 163   RenderFrameHostManager::Delegate* manager_delegate_;
 164
 165   // Map of SiteInstance ID to a RenderViewHost.  This allows us to look up the
 166   // RenderViewHost for a given SiteInstance when creating RenderFrameHosts.
 167   // Combined with the refcount on RenderViewHost, this allows us to call
 168   // Shutdown on the RenderViewHost and remove it from the map when no more
 169   // RenderFrameHosts are using it.
 170   //
 171   // Must be declared before |root_| so that it is deleted afterward.  Otherwise
 172   // the map will be cleared before we delete the RenderFrameHosts in the tree.
 173   RenderViewHostMap render_view_host_map_;
 174
 175   // Map of SiteInstance ID to RenderViewHosts that are pending shutdown. The
 176   // renderers of these RVH are currently executing the unload event in
 177   // background. When the SwapOutACK is received, they will be deleted. In the
 178   // meantime, they are kept in this map, as they should not be reused (part of
 179   // their state is already gone away).
 180   RenderViewHostMultiMap render_view_host_pending_shutdown_map_;
 181
 182   scoped_ptr<FrameTreeNode> root_;
 183
 184   int focused_frame_tree_node_id_;
 185
 186   base::Callback<void(RenderFrameHost*)> on_frame_removed_;
 187
 188   // Overall load progress.
 189   double load_progress_;
 190
 191   DISALLOW_COPY_AND_ASSIGN(FrameTree);
 192 };
 193
 194 }  // namespace content
 195
 196 #endif  // CONTENT_BROWSER_FRAME_HOST_FRAME_TREE_H_