content/browser/browsing_instance.h

   1 // Copyright (c) 2012 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_BROWSING_INSTANCE_H_
   6 #define CONTENT_BROWSER_BROWSING_INSTANCE_H_
   7
   8 #include "base/hash_tables.h"
   9 #include "base/lazy_instance.h"
  10 #include "base/memory/ref_counted.h"
  11 #include "content/common/content_export.h"
  12 #include "content/public/browser/browser_context.h"
  13
  14 class GURL;
  15
  16 namespace content {
  17 class SiteInstance;
  18 class SiteInstanceImpl;
  19
  20 ///////////////////////////////////////////////////////////////////////////////
  21 //
  22 // BrowsingInstance class
  23 //
  24 // A browsing instance corresponds to the notion of a "unit of related browsing
  25 // contexts" in the HTML 5 spec.  Intuitively, it represents a collection of
  26 // tabs and frames that can have script connections to each other.  In that
  27 // sense, it reflects the user interface, and not the contents of the tabs and
  28 // frames.
  29 //
  30 // We further subdivide a BrowsingInstance into SiteInstances, which represent
  31 // the documents within each BrowsingInstance that are from the same site and
  32 // thus can have script access to each other.  Different SiteInstances can
  33 // safely run in different processes, because their documents cannot access
  34 // each other's contents (due to the same origin policy).
  35 //
  36 // It is important to only have one SiteInstance per site within a given
  37 // BrowsingInstance.  This is because any two documents from the same site
  38 // might be able to script each other if they are in the same BrowsingInstance.
  39 // Thus, they must be rendered in the same process.
  40 //
  41 // A BrowsingInstance is live as long as any SiteInstance has a reference to
  42 // it.  A SiteInstance is live as long as any NavigationEntry or RenderViewHost
  43 // have references to it.  Because both classes are RefCounted, they do not
  44 // need to be manually deleted.
  45 //
  46 // BrowsingInstance has no public members, as it is designed to be
  47 // visible only from the SiteInstance class.  To get a new
  48 // SiteInstance that is part of the same BrowsingInstance, use
  49 // SiteInstance::GetRelatedSiteInstance.  Because of this,
  50 // BrowsingInstances and SiteInstances are tested together in
  51 // site_instance_unittest.cc.
  52 //
  53 ///////////////////////////////////////////////////////////////////////////////
  54 class CONTENT_EXPORT BrowsingInstance
  55     : public base::RefCounted<BrowsingInstance> {
  56  protected:
  57   // Create a new BrowsingInstance.
  58   explicit BrowsingInstance(BrowserContext* context);
  59
  60   // Get the browser context to which this BrowsingInstance belongs.
  61   BrowserContext* browser_context() const { return browser_context_; }
  62
  63   // Returns whether this BrowsingInstance has registered a SiteInstance for
  64   // the site of the given URL.
  65   bool HasSiteInstance(const GURL& url);
  66
  67   // Get the SiteInstance responsible for rendering the given URL.  Should
  68   // create a new one if necessary, but should not create more than one
  69   // SiteInstance per site.
  70   SiteInstance* GetSiteInstanceForURL(const GURL& url);
  71
  72   // Adds the given SiteInstance to our map, to ensure that we do not create
  73   // another SiteInstance for the same site.
  74   void RegisterSiteInstance(SiteInstance* site_instance);
  75
  76   // Removes the given SiteInstance from our map, after all references to it
  77   // have been deleted.  This means it is safe to create a new SiteInstance
  78   // if the user later visits a page from this site, within this
  79   // BrowsingInstance.
  80   void UnregisterSiteInstance(SiteInstance* site_instance);
  81
  82   friend class SiteInstanceImpl;
  83   friend class SiteInstance;
  84
  85   friend class base::RefCounted<BrowsingInstance>;
  86
  87   // Virtual to allow tests to extend it.
  88   virtual ~BrowsingInstance();
  89
  90  private:
  91   // Map of site to SiteInstance, to ensure we only have one SiteInstance per
  92   typedef base::hash_map<std::string, SiteInstance*> SiteInstanceMap;
  93
  94   // Common browser context to which all SiteInstances in this BrowsingInstance
  95   // must belong.
  96   BrowserContext* const browser_context_;
  97
  98   // Map of site to SiteInstance, to ensure we only have one SiteInstance per
  99   // site.  The site string should be the possibly_invalid_spec() of a GURL
 100   // obtained with SiteInstanceImpl::GetSiteForURL.  Note that this map may not
 101   // contain every active SiteInstance, because a race exists where two
 102   // SiteInstances can be assigned to the same site.  This is ok in rare cases.
 103   SiteInstanceMap site_instance_map_;
 104
 105   DISALLOW_COPY_AND_ASSIGN(BrowsingInstance);
 106 };
 107
 108 }  // namespace content
 109
 110 #endif  // CONTENT_BROWSER_BROWSING_INSTANCE_H_