Add documentation for Android WebView CookieManager initialization

This took me a while to completely figure out, so I'm adding an overly
lengthy comment explaining how it works.

Bug: None
Change-Id: I73c511e690b044a938bb3bb0f154ad8982bcfd1c
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/1872424Reviewed-by: Richard Coles <torne@chromium.org>
Reviewed-by: Nate Fischer <ntfschr@chromium.org>
Commit-Queue: Lily Chen <chlily@chromium.org>
Cr-Commit-Position: refs/heads/master@{#708607}

android_webview/browser/cookie_manager.h

@@ -36,6 +36,49 @@ namespace android_webview {
 // Since Java calls can be made on the IO Thread, and must synchronously return
 // a result, and the CookieStore API allows it to asynchronously return results,
 // the CookieStore must be run on its own thread, to prevent deadlock.
+//
+// Initialization:
+//
+// There are two possible scenarios: 1) The CookieManager is used before the
+// Network Service is initialized. 2) The CookieManager is not used until after
+// the Network Service is initialized (during content initialization).
+//
+// Case 2) is straightforward: Once the NetworkContext and the
+// network::mojom::CookieManager are created, the AwContentBrowserClient calls
+// PassMojoCookieManagerToAwCookieManager, which ends up calling
+// CookieManager::SwapMojoCookieManagerAsync, setting the |mojo_cookie_manager_|
+// member of CookieManager (the AW one; it's an unfortunately overloaded term).
+//
+// In case 1), the CookieManager creates a provisional CookieStore
+// |cookie_store_|, which it uses for all operations (because the
+// network::mojom::CookieManager doesn't exist yet): For every cookie task
+// it receives, the CookieManager first checks for the presence of a
+// |mojo_cookie_manager_|, and if it doesn't exist, the CookieManager checks for
+// the presence of a provisionally-created CookieStore, creating one if it
+// doesn't exist (in GetCookieStore). Then whichever one it found will handle
+// the cookie task.
+//
+// When it comes time to create the NetworkContext, which comes with a
+// network::mojom::CookieManager, the provisionally-created CookieStore needs to
+// transfer its contents (with the results of the pre-content-initialization
+// cookie tasks) to the newly created network::mojom::CookieManager. It does
+// this by flushing its contents to disk and then calling the same method,
+// CookieManager::SwapMojoCookieManagerAsync, which binds the newly created
+// network::mojom::CookieManager to |mojo_cookie_manager_|. Thereafter, any
+// cookie tasks will be handled by |mojo_cookie_manager_| because it now exists.
+//
+// This works because the newly created network::mojom::CookieManager reads from
+// the same on-disk backing store that the provisionally-created CookieStore
+// just flushed its contents to.
+//
+// Why is this not a race condition? This was addressed in crbug.com/933461.
+// If the CookieManager receives cookie tasks while the flush is in progress,
+// those tasks are added to a task queue, which is not executed until after the
+// new |mojo_cookie_manager_| has finished being set. The new
+// |mojo_cookie_manager_| only loads from disk upon receiving a task (*not* upon
+// creation, importantly; see CookieMonster::FetchAllCookiesIfNecessary, which
+// is only called if cookie tasks are received), so it will not try to load from
+// disk until the flush is complete.
 class CookieManager {
  public:
   static CookieManager* GetInstance();