use recommended page lifecycle state

Lets the browser engine freeze or discard inactive tabs, reducing resource consumption
and increasing battery life.

doc/help/settings.asciidoc

@@ -293,9 +293,12 @@
 |<<prompt.radius,prompt.radius>>|Rounding radius (in pixels) for the edges of prompts.
 |<<qt.args,qt.args>>|Additional arguments to pass to Qt, without leading `--`.
 |<<qt.chromium.experimental_web_platform_features,qt.chromium.experimental_web_platform_features>>|Enables Web Platform features that are in development.
+|<<qt.chromium.lifecycle_state_discard_delay,qt.chromium.lifecycle_state_discard_delay>>|The amount of time (in milliseconds) to wait before transitioning a page to the discarded lifecycle state.
+|<<qt.chromium.lifecycle_state_freeze_delay,qt.chromium.lifecycle_state_freeze_delay>>|The amount of time (in milliseconds) to wait before transitioning a page to the frozen lifecycle state.
 |<<qt.chromium.low_end_device_mode,qt.chromium.low_end_device_mode>>|When to use Chromium's low-end device mode.
 |<<qt.chromium.process_model,qt.chromium.process_model>>|Which Chromium process model to use.
 |<<qt.chromium.sandboxing,qt.chromium.sandboxing>>|What sandboxing mechanisms in Chromium to use.
+|<<qt.chromium.use_recommended_page_lifecycle_state,qt.chromium.use_recommended_page_lifecycle_state>>|Use recommended page lifecycle state.
 |<<qt.environ,qt.environ>>|Additional environment variables to set.
 |<<qt.force_platform,qt.force_platform>>|Force a Qt platform to use.
 |<<qt.force_platformtheme,qt.force_platformtheme>>|Force a Qt platformtheme to use.
@@ -3845,6 +3848,26 @@ Valid values:
 
 Default: +pass:[auto]+
 
+[[qt.chromium.lifecycle_state_discard_delay]]
+=== qt.chromium.lifecycle_state_discard_delay
+The amount of time (in milliseconds) to wait before transitioning a page to the discarded lifecycle state.
+
+This setting is only available with the QtWebEngine backend.
+
+Type: <<types,Int>>
+
+Default: +pass:[0]+
+
+[[qt.chromium.lifecycle_state_freeze_delay]]
+=== qt.chromium.lifecycle_state_freeze_delay
+The amount of time (in milliseconds) to wait before transitioning a page to the frozen lifecycle state.
+
+This setting is only available with the QtWebEngine backend.
+
+Type: <<types,Int>>
+
+Default: +pass:[0]+
+
 [[qt.chromium.low_end_device_mode]]
 === qt.chromium.low_end_device_mode
 When to use Chromium's low-end device mode.
@@ -3912,6 +3935,19 @@ Valid values:
 
 Default: +pass:[enable-all]+
 
+[[qt.chromium.use_recommended_page_lifecycle_state]]
+=== qt.chromium.use_recommended_page_lifecycle_state
+Use recommended page lifecycle state.
+This puts webpages into one of three lifecycle states: active, frozen, or discarded. Using the recommended lifecycle state lets the browser use less resources by freezing or discarding web views when it's safe to do so.
+This results in significant battery life savings.
+Ongoing page activity is taken into account when determining the recommended lifecycle state, as to not disrupt your browsing.
+
+This setting is only available with the QtWebEngine backend.
+
+Type: <<types,Bool>>
+
+Default: +pass:[false]+
+
 [[qt.environ]]
 === qt.environ
 Additional environment variables to set.

qutebrowser/browser/webengine/webenginetab.py

@@ -1316,6 +1316,8 @@ class WebEngineTab(browsertab.AbstractTab):
         self._child_event_filter = None
         self._saved_zoom = None
         self._scripts.init()
+        self._lifecycle_timer = usertypes.Timer(self)
+        self._lifecycle_timer.setSingleShot(True)
         # WORKAROUND for https://bugreports.qt.io/browse/QTBUG-65223
         self._needs_qtbug65223_workaround = (
             version.qtwebengine_versions().webengine < utils.VersionNumber(5, 15, 5))
@@ -1424,6 +1426,14 @@ class WebEngineTab(browsertab.AbstractTab):
         # percent encoded content is 2 megabytes minus 30 bytes.
         self._widget.setHtml(html, base_url)
 
+    def _set_lifecycle_state(
+        self,
+        new_state: QWebEnginePage.LifecycleState,
+    ) -> None:
+        """Set the lifecycle state of the current tab."""
+        log.webview.debug(f"Setting page lifecycle state of {self} to {new_state}")
+        self._widget.page().setLifecycleState(new_state)
+
     def _show_error_page(self, url, error):
         """Show an error page in the tab."""
         log.misc.debug("Showing error page for {}".format(error))
@@ -1724,6 +1734,30 @@ class WebEngineTab(browsertab.AbstractTab):
         else:
             selection.selectNone()
 
+    @pyqtSlot(QWebEnginePage.LifecycleState)
+    def _on_recommended_state_changed(
+            self,
+            recommended_state: QWebEnginePage.LifecycleState,
+    ) -> None:
+        disabled = not config.val.qt.chromium.use_recommended_page_lifecycle_state
+
+        # If the config is changed at runtime, stop freezing/discarding pages, but do
+        # recover pages that become active again.
+        if disabled and recommended_state != QWebEnginePage.LifecycleState.Active:
+            return
+
+        if recommended_state == QWebEnginePage.LifecycleState.Frozen:
+            delay = config.val.qt.chromium.lifecycle_state_freeze_delay
+        elif recommended_state == QWebEnginePage.LifecycleState.Discarded:
+            delay = config.val.qt.chromium.lifecycle_state_discard_delay
+        else:
+            delay = 0
+
+        self._lifecycle_timer.timeout.disconnect()
+        log.webview.debug(f"Setting lifecycle state {recommended_state} in {delay}ms")
+        self._lifecycle_timer.timeout.connect(lambda: self._set_lifecycle_state(recommended_state))
+        self._lifecycle_timer.start(delay)
+
     def _connect_signals(self):
         view = self._widget
         page = view.page()
@@ -1742,6 +1776,8 @@ class WebEngineTab(browsertab.AbstractTab):
         page.printRequested.connect(self._on_print_requested)
         page.selectClientCertificate.connect(self._on_select_client_certificate)
 
+        page.recommendedStateChanged.connect(self._on_recommended_state_changed)
+
         view.titleChanged.connect(self.title_changed)
         view.urlChanged.connect(self._on_url_changed)
         view.renderProcessTerminated.connect(

qutebrowser/config/configdata.yml

@@ -345,6 +345,38 @@ qt.chromium.experimental_web_platform_features:
     Chromium. By default, this is enabled with Qt 5 to maximize compatibility
     despite an aging Chromium base.
 
+qt.chromium.use_recommended_page_lifecycle_state:
+  type: Bool
+  default: false
+  backend: QtWebEngine
+  desc: >-
+    Use recommended page lifecycle state.
+
+    This puts webpages into one of three lifecycle states: active, frozen, or
+    discarded. Using the recommended lifecycle state lets the browser use less
+    resources by freezing or discarding web views when it's safe to do so.
+
+    This results in significant battery life savings.
+
+    Ongoing page activity is taken into account when determining the
+    recommended lifecycle state, as to not disrupt your browsing.
+
+qt.chromium.lifecycle_state_freeze_delay:
+  type: Int
+  default: 0
+  backend: QtWebEngine
+  desc: >-
+    The amount of time (in milliseconds) to wait before transitioning a page to
+    the frozen lifecycle state.
+
+qt.chromium.lifecycle_state_discard_delay:
+  type: Int
+  default: 0
+  backend: QtWebEngine
+  desc: >-
+    The amount of time (in milliseconds) to wait before transitioning a page to
+    the discarded lifecycle state.
+
 qt.highdpi:
   type: Bool
   default: false