tor-browser

The Tor Browser
git clone https://git.dasho.dev/tor-browser.git
Log | Files | Refs | README | LICENSE

priority-hint.rst (2160B)

      1 GeckoView Priority Hint API
      2 ===========================
      3 
      4 Cathy Lu <calu@mozilla.com>, `Bug 1764998 <https://bugzilla.mozilla.org/show_bug.cgi?id=1764998>`_
      5 
      6 May 2nd, 2022
      7 
      8 Summary
      9 -------
     10 
     11 This document describes the API for setting a process to high priority by
     12 applying a high priority hint. Instead of deducing the priority based on the
     13 extension’s active priority, this will add an API to set it explicitly.
     14 
     15 Motivation
     16 ----------
     17 
     18 This API will allow Glean metrics to be measured in order to compare
     19 performance and stability metrics for process prioritization on vs off.
     20 Previously, prioritization depended on whether or not a ``GeckoSession`` had a
     21 surface associated with it, which lowered the priority of background tabs and
     22 needed to be reloaded more often.
     23 
     24 Goals
     25 -----
     26 
     27 Apps can set ``priorityHint`` on a ``GeckoSession``.
     28 
     29 Existing Work
     30 -------------
     31 
     32 In `bug 1753700 <https://bugzilla.mozilla.org/show_bug.cgi?id=1753700>`_, we
     33 added an API in dom/ipc to allow ``GeckoViewWebExtension`` to set a specific
     34 ``remoteTab``’s boolean ``priorityHint``. This allows tabs that do not have a
     35 surface but are active according to web extension to have high priority.
     36 
     37 Implementation
     38 --------------
     39 
     40 In ``GeckoSession``, add an API ``setPriorityHint`` that takes an integer as a
     41 parameter. The priority int can be ``PRIORITY_DEFAULT`` or ``PRIORITY_HIGH``.
     42 Specified and active tabs would be ``PRIORITY_HIGH``. The default would be
     43 ``PRIORITY_DEFAULT``. The API will dispatch an event
     44 ``GeckoView:SetPriorityHint``.
     45 
     46 .. code:: java
     47 
     48  public void setPriorityHint(final @Priority int priorityHint)
     49 
     50 Listeners in ``GeckoViewContent.sys.mjs`` will set
     51 ``this.browser.frameLoader.remoteTab.priorityHint`` to the boolean passed in.
     52 
     53 .. code:: java
     54 
     55  case "GeckoView:setPriorityHint":
     56    if (this.browser.isRemoteBrowser) {
     57      let remoteTab = this.browser.frameLoader?.remoteTab;
     58      if (remoteTab) {
     59        remoteTab.renderLayers.priorityHint = val;
     60      }
     61    }
     62  break;
     63 
     64 Additional Complexities
     65 -----------------------
     66 
     67 Apps that use this API will need to manually use the API to set the
     68 priorityHint when the tab goes to foreground or background.