WebEngine Lifecycle Example

Freezes and discards background tabs to reduce CPU and memory usage.

WebEngine Lifecycle Example demonstrates how the lifecycleState and recommendedState properties of the WebEngineView can be used to reduce the CPU and memory usage of background tabs in a tabbed browser.

Running the Example

To run the example from Qt Creator, open the Welcome mode and select the example from Examples. For more information, visit Building and Running an Example.

UI Elements of the Example

The example uses Qt Quick Controls 2 to implement a traditional tabbed browser in the Material Style (dark variant). The main application window (WebBrowser.qml) is divided into a header bar at the top and a main viewing area filling the rest of the window. The header contains the tab bar (WebTabBar.qml) with one button per tab (WebTabButton.qml). The main area consists of a stack of tabs (WebTabStack.qml and WebTab.qml). Each tab in turn has a tool bar at the top and a WebEngineView for displaying web pages. Finally, the main window also has a Drawer for changing settings. The drawer can be opened by clicking the "⋮" button on the tool bar.

Overview of Lifecycle States

Each WebEngineView item can be in one of three lifecycle states: active, frozen, or discarded. These states, like the sleep states of a CPU, control the resource usage of web views.

The active state is the normal, unrestricted state of a web view. All visible web views are always in the active state, as are all web views that have not yet finished loading. Only invisible, idle web views can be transitioned to other lifecycle states.

The frozen state is a low CPU usage state. In this state, most HTML task sources are suspended (frozen) and, as a result, most DOM event processing and JavaScript execution will also be suspended. The web view must be invisible in order to be frozen as rendering is not possible in this state.

The discarded state is an extreme resource-saving state. In this state, the browsing context of the web view will be discarded and the corresponding renderer subprocess shut down. CPU and memory usage in this state is reduced virtually to zero. On exiting this state the web page will be automatically reloaded. The process of entering and exiting the discarded state is similar to serializing the browsing history of the web view and destroying the view, then creating a new view and restoring its history.

See also WebEngineView::LifecycleState. The equivalent in the Widgets API is QWebEnginePage::LifecycleState.

The lifecycleState and recommendedState Properties

The lifecycleState property of the WebEngineView type is a read-write property that controls the current lifecycle state of the web view. This property is designed to place as few restrictions as possible on what states can be transitioned to. For example, it is allowed to freeze a web view that is currently playing music in the background, stopping the music. In order to implement a less aggressive resource-saving strategy that avoids interrupting user-visible background activity, the recommendedState property must be used.

The recommendedState property of the WebEngineView type is a read-only property that calculates a safe limit on the lifecycleState property, taking into account the current activity of the web view. So, in the example of a web view playing music in the background, the recommended state will be Active since a more aggressive state would stop the music. If the application wants to avoid interrupting background activity, then it should avoid putting the web view into a more aggressively resource-saving lifecycle state than what's given by recommendedState.

See also WebEngineView::lifecycleState and WebEngineView::recommendedState. The equivalents in the Widgets API are QWebEnginePage::lifecycleState and QWebEnginePage::recommendedState.

The Page Lifecycle API

The lifecycleState property is connected to the Page Lifecycle API, a work-in-progress extension to the HTML standard that specifies two new DOM events, freeze and resume, and adds a new Document.wasDiscarded boolean property. The freeze and resume events are fired when transitioning from the Active to the Frozen state, and vice-versa. The Document.wasDiscarded property is set to true when transition from the Discarded state to the Active state.

Lifecycle States in the Example

The example implements two ways of changing the lifecycle state: manual and automatic. The manual way uses the lifecycleState property directly to change the web view lifecycle state, while the automatic way is timer-based and also takes into account the recommendedState.

The tab titles in the tab bar are color coded with frozen tabs shown in blue and discarded in red.

Manual Lifecycle Control

Manual control is provided by context menus on the tab bar buttons (WebTabButton.qml). The menu has three radio buttons, one for each lifecycle state, with the current state checked. Some buttons may be disabled, either because they represent illegal state transitions (for example, a Discarded view cannot directly transition to the Frozen state), or because other preconditions are not fulfilled (for example, a visible view can only be in the Active state).

Automatic Lifecycle Control

Automatic control is implemented with a Timer in the WebTab component (WebTab.qml). The timer is started whenever the lifecycleState of the web view does not match it's recommendedState. Once the timer fires, the view's lifecycle state is set to the recommended state.

The time delay is used to avoid changing the lifecycle state too quickly when the user is switching between tabs. The freezing and discarding delays can be changed in the settings drawer accessed through the "⋮" button on the tool bar.

This is a rather simple algorithm for automatic lifecycle control, however more sophisticated algorithms could also be conceived and implemented on the basis of the lifecycleState property. For example, the Chromium browser experimentally uses a pretrained deep neural network to predict the next tab activation time by the user, essentially ranking tabs based on how interesting they are to the user. Implementing such an algorithm is left as an exercise to the reader for now.

Example project @ code.qt.io

© 2019 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.