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.sys.mjs`` 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.