1 files changed, 68 insertions, 0 deletions
diff --git a/mobile/android/docs/geckoview/design/priority-hint.rst b/mobile/android/docs/geckoview/design/priority-hint.rst
new file mode 100644
index 0000000000..4a915bb7ed
--- /dev/null
+++ b/mobile/android/docs/geckoview/design/priority-hint.rst
@@ -0,0 +1,68 @@
+GeckoView Priority Hint API
+===========================
+
+Cathy Lu <calu@mozilla.com>, `Bug 1764998 <https://bugzilla.mozilla.org/show_bug.cgi?id=1764998>`_
+
+May 2nd, 2022
+
+Summary
+-------
+
+This document describes the API for setting a process to high priority by
+applying a high priority hint. Instead of deducing the priority based on the
+extension’s active priority, this will add an API to set it explicitly.
+
+Motivation
+----------
+
+This API will allow Glean metrics to be measured in order to compare
+performance and stability metrics for process prioritization on vs off.
+Previously, prioritization depended on whether or not a ``GeckoSession`` had a
+surface associated with it, which lowered the priority of background tabs and
+needed to be reloaded more often.
+
+Goals
+-----
+
+Apps can set ``priorityHint`` on a ``GeckoSession``.
+
+Existing Work
+-------------
+
+In `bug 1753700 <https://bugzilla.mozilla.org/show_bug.cgi?id=1753700>`_, we
+added an API in dom/ipc to allow ``GeckoViewWebExtension`` to set a specific
+``remoteTab``’s boolean ``priorityHint``. This allows tabs that do not have a
+surface but are active according to web extension to have high priority.
+
+Implementation
+--------------
+
+In ``GeckoSession``, add an API ``setPriorityHint`` that takes an integer as a
+parameter. The priority int can be ``PRIORITY_DEFAULT`` or ``PRIORITY_HIGH``.
+Specified and active tabs would be ``PRIORITY_HIGH``. The default would be
+``PRIORITY_DEFAULT``. The API will dispatch an event
+``GeckoView:SetPriorityHint``.
+
+.. code:: java
+
+  public void setPriorityHint(final @Priority int priorityHint)
+
+Listeners in ``GeckoViewContent.jsm`` will set
+``this.browser.frameLoader.remoteTab.priorityHint`` to the boolean passed in.
+
+.. code:: java
+
+  case "GeckoView:setPriorityHint":
+    if (this.browser.isRemoteBrowser) {
+      let remoteTab = this.browser.frameLoader?.remoteTab;
+      if (remoteTab) {
+        remoteTab.renderLayers.priorityHint = val;
+      }
+    }
+  break;
+
+Additional Complexities
+-----------------------
+
+Apps that use this API will need to manually use the API to set the
+priorityHint when the tab goes to foreground or background.