aw: Added Threading document.

This CL moves the "Android WebView and the UI thread" document at:

https://docs.google.com/document/d/1sDMN-K4TPh8osNBt-4ANfhf9FrRWl3xxrGRp7O-hkB8

into Markdown.

Bug: None
Change-Id: Ia33d68f92b881485c43b7a7dcfab37f8cfabf258
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/1746488
Commit-Queue: Chris Mumford <cmumford@google.com>
Reviewed-by: Nate Fischer <ntfschr@chromium.org>
Cr-Commit-Position: refs/heads/master@{#686423}

android_webview/docs/navbar.md

@@ -11,6 +11,7 @@
 * [Net debugging](/android_webview/docs/net-debugging.md)
 * [FAQ (for users)](/android_webview/docs/faq.md)
 * [AOSP system integration](/android_webview/docs/aosp-system-integration.md)
+* [Threading](/android_webview/docs/threading.md)
 
 [home]: /android_webview/docs/README.md
 [logo]: /android_webview/docs/images/webview_logo.png

android_webview/docs/threading.md

+# Android WebView and the UI thread
+
+This document describes how the Chromium based Android WebView reconciles with
+mismatching requirements and assumptions between Android and Chromium about the
+UI thread.
+
+
+## The UI Thread in Chromium
+
+In Chromium, there is a single global **UI** thread in the browser process. It
+is one of the explicitly named
+[BrowserThreads](/content/public/browser/browser_thread.h).
+The **UI** thread is generally where UI code runs, including input delivery from
+the OS.
+
+The concept of “the one and only **UI** thread” is well established in content
+layer and above. For example, all WebContents live on this **UI** thread.
+
+
+## View Threads in Android
+
+A [Window](http://developer.android.com/reference/android/view/Window.html), its
+view tree, and [Views](https://developer.android.com/reference/android/view/View)
+in that tree are all single threaded in general; for a particular View, call
+this the **view** thread. It is possible to create separate Windows and view
+trees on separate threads, as long as Views are not moved between them. So there
+can be more than one **view** thread.
+
+Most apps do not make use of this hidden feature; they use a single view tree on
+the [main thread](http://developer.android.com/reference/android/os/Looper.html#getMainLooper())
+of the application. However, in general, it’s not safe to assume there’s only a
+single **view** thread, or that the **view** thread and the **main** thread is
+the same.
+
+
+## Best effort solution
+
+WebView’s solution is use the first **view** thread as the **UI** thread, then
+post non-**UI** thread calls to the **UI** thread, and block if needed.
+
+Because Chromium initialization identifies the thread as the UI thread, parts of
+this solution runs before Chromium is initialized. The implementation is in the
+android webview glue layer, specifically in
+[WebViewChromium](../glue/java/src/com/android/webview/chromium/WebViewChromium.java)
+and [WebViewChromiumFactoryProvider](../glue/java/src/com/android/webview/chromium/WebViewChromiumFactoryProvider.java).
+The idea is hold off initializing chromium until a **view** thread is identified.
+
+**View** thread can be identified by certain View methods. For example,
+[onAttachedToWindow](http://developer.android.com/reference/android/view/View.html#onAttachedToWindow())
+is called by the view tree on the **view** thread. Of course this is not 100%
+reliable since apps could call those methods as well.
+
+In case a method that cannot be held off is called before a view thread is
+identified, the **main** thread is used as the **UI** thread. Methods calls that
+are not held off include:
+
+*   Methods with an immediate output with no meaningful defaults without initialization.
+    *   onDraw: Need to draw into canvas parameter
+    *   Any method with a return value, like getHttpAuthUsernamePassword.
+*   “Important” calls that should not be held off. This is a judgement call mostly.
+    *   Currently only loadUrl and loadData family of calls
+
+
+## View is Single-Threaded
+
+Views in android are expected to be created and used on its single **view**
+thread, unless otherwise noted in the API. For WebView, this is enforced for
+apps targeting JB MR2 or above. The code lives in the
+[WebView](https://github.com/android/platform_frameworks_base/blob/master/core/java/android/webkit/WebView.java).
+Note this is an orthogonal concern to the single **UI** thread described above,
+as this check still allows different WebViews to be used on different **view**
+threads.