Fix issues related to request and context object lifespan (issue #1037, issue #1044).

- Simplify and document the relationship between the various context object types. See browser_context.h for a description of the new relationships.
- cefclient: Add `request-context-per-browser` command-line flag for testing multiple CefRequestContext instances.
- cefclient: Add a CefURLRequest example.

git-svn-id: https://chromiumembedded.googlecode.com/svn/trunk@2032 5089003a-bbd8-11dd-ad1f-f1f9622dbc98

libcef/browser/browser_context.h

@@ -6,11 +6,115 @@
 #define CEF_LIBCEF_BROWSER_BROWSER_CONTEXT_H_
 #pragma once
 
+#include "libcef/browser/resource_context.h"
+
 #include "content/public/browser/browser_context.h"
+#include "content/public/browser/browser_thread.h"
 #include "content/public/browser/content_browser_client.h"
 
-class CefBrowserContext : public content::BrowserContext {
+/*
+// Classes used in request processing (network, storage, service, etc.):
+//
+// WC = WebContents
+//  Content API representation of a browser. Created by BHI or the system (for
+//  popups) and owned by BHI. Keeps a pointer to BCI/BCP.
+//
+// BHI = CefBrowserHostImpl
+//  Implements the CefBrowser and CefBrowserHost interfaces which are exposed
+//  to clients. References an RCI instance. Owns a WC. Life span is controlled
+//  by client references and CefContentBrowserClient.
+//
+// RCI = CefRequestContextImpl
+//  Implements the CefRequestContext interface which is exposed to clients.
+//  References the global BCI or creates a new BCP.
+//
+// BCI = CefBrowserContextImpl
+//   Entry point from WC when using the global RCI. Owns the RC and creates the
+//   URCGI. Life span controlled by RCI and CefBrowserMainParts.
+//
+// BCP = CefBrowserContextProxy
+//   Entry point from WC when using a custom RCI. Owns the RC and creates the
+//   URCGP. Life span controlled by RCI.
+//
+// RC = CefResourceContext
+//   Acts as a bridge for resource loading. URLRequest life span is tied to this
+//   object. Must be destroyed before the associated URCGI/URCGP. Life span is
+//   controlled by BCI/BCP.
+//
+// URCGI = CefURLRequestContextGetterImpl
+//   Creates and owns the URCI. Life span is controlled by RC and
+//   CefBrowserMainParts.
+//
+// URCGP = CefURLRequestContextGetterProxy
+//   Creates and owns the URCP. Life span is controlled by RC.
+//
+// URCI = CefURLRequestContextImpl
+//   Owns various network-related objects including the global cookie manager.
+//   Owns URLRequest objects which must be destroyed first. Life span is
+//   controlled by URCGI.
+//
+// URCP = CefURLRequestContextProxy
+//   Creates the CSP and forwards requests to the objects owned by URCI. Owns
+//   URLRequest objects which must be destroyed first. Life span is controlled
+//   by URCGP.
+//
+// CSP = CefCookieStoreProxy
+//   Gives the CefCookieManager instance retrieved via CefRequestContextHandler
+//   an opportunity to handle cookie requests. Otherwise forwards requests via
+//   URCI to the global cookie manager. Life span is controlled by URCP.
+//
+//
+// Relationship diagram:
+//   ref = reference (CefRefPtr/scoped_refptr)
+//   own = ownership (scoped_ptr)
+//   ptr = raw pointer
+//
+//                    CefBrowserMainParts      global cookie manager, etc...
+//                       |           |            ^
+//                      ref         ref        ref/own
+//                       v           v            |
+//                /---> BCI -ref-> URCGI --own-> URCI <-ptr-- CSP
+//               /       ^           ^                        ^
+//             ptr      ref         ref                      /
+//             /         |           |                      /
+// BHI -own-> WC -ptr-> BCP -ref-> URCGP -own-> URCP --ref-/
+//
+// BHI -ref-> RCI -ref-> BCI/BCP -own-> RC -ref-> URCGI/URCGP
+//
+//
+// How shutdown works:
+// 1. CefBrowserHostImpl is destroyed on any thread due to browser close,
+//    ref release, etc.
+// 2. CefRequestContextImpl is destroyed on any thread due to
+//    CefBrowserHostImpl destruction, ref release, etc.
+// 3. CefBrowserContext* is destroyed on the UI thread due to
+//    CefRequestContextImpl destruction (*Impl, *Proxy) or ref release in
+//    CefBrowserMainParts::PostMainMessageLoopRun() (*Impl).
+// 4. CefResourceContext is destroyed asynchronously on the IO thread due to
+//    CefBrowserContext* destruction. This cancels/destroys any pending
+//    URLRequests.
+// 5. CefURLRequestContextGetter* is destroyed asynchronously on the IO thread
+//    due to CefResourceContext destruction (*Impl, *Proxy) or ref release in
+//    CefBrowserMainParts::PostMainMessageLoopRun() (*Impl). This may be delayed
+//    if other network-related objects still have a reference to it.
+// 6. CefURLRequestContext* is destroyed on the IO thread due to
+//    CefURLRequestContextGetter* destruction. 
+*/
+
+// Main entry point for configuring behavior on a per-browser basis. An instance
+// of this class is passed to WebContents::Create in CefBrowserHostImpl::
+// CreateInternal. Only accessed on the UI thread.
+class CefBrowserContext
+    : public content::BrowserContext,
+      public base::RefCountedThreadSafe<
+          CefBrowserContext, content::BrowserThread::DeleteOnUIThread> {
  public:
+  CefBrowserContext();
+
+  // BrowserContext methods.
+  content::ResourceContext* GetResourceContext() override;
+
+  // Called from CefContentBrowserClient to create the URLRequestContextGetter.
   virtual net::URLRequestContextGetter* CreateRequestContext(
       content::ProtocolHandlerMap* protocol_handlers,
       content::URLRequestInterceptorScopedVector request_interceptors) = 0;
@@ -19,6 +123,28 @@ class CefBrowserContext : public content::BrowserContext {
       bool in_memory,
       content::ProtocolHandlerMap* protocol_handlers,
       content::URLRequestInterceptorScopedVector request_interceptors) = 0;
+
+  CefResourceContext* resource_context() const {
+      return resource_context_.get();
+  }
+
+#ifndef NDEBUG
+  // Simple tracking of allocated objects.
+  static base::AtomicRefCount DebugObjCt;  // NOLINT(runtime/int)
+#endif
+
+ protected:
+  ~CefBrowserContext() override;
+
+ private:
+  // Only allow deletion via scoped_refptr().
+  friend struct content::BrowserThread::DeleteOnThread<
+      content::BrowserThread::UI>;
+  friend class base::DeleteHelper<CefBrowserContext>;
+
+  scoped_ptr<CefResourceContext> resource_context_;
+
+  DISALLOW_COPY_AND_ASSIGN(CefBrowserContext);
 };
 
 #endif  // CEF_LIBCEF_BROWSER_BROWSER_CONTEXT_H_