# GeckoView Priority Hint API

Cathy Lu \<<mailto: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`.

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

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