feat: disable background throttling (#12181)

Co-authored-by: Fabian-Lars <github@fabianlars.de>

Author: bastiankistner

.changes/disable-background-throttling.md

@@ -0,0 +1,11 @@
+---
+'tauri-cli': 'minor:enhance'
+'tauri-runtime': 'minor:enhance'
+'tauri-runtime-wry': 'minor:enhance'
+'tauri-utils': 'minor:enhance'
+'tauri': 'minor:enhance'
+'@tauri-apps/api': 'minor:enhance'
+'@tauri-apps/cli': 'minor:enhance'
+---
+
+Add an option to change the default background throttling policy (currently for WebKit only).

Cargo.lock

@@ -516,6 +516,17 @@
               "type": "null"
             }
           ]
+        },
+        "backgroundThrottling": {
+          "description": "Change the default background throttling behaviour.\n\n By default, browsers use a suspend policy that will throttle timers and even unload\n the whole tab (view) to free resources after roughly 5 minutes when a view became\n minimized or hidden. This will pause all tasks until the documents visibility state\n changes back from hidden to visible by bringing the view back to the foreground.\n\n ## Platform-specific\n\n - **Linux / Windows / Android**: Unsupported. Workarounds like a pending WebLock transaction might suffice.\n - **iOS**: Supported since version 17.0+.\n - **macOS**: Supported since version 14.0+.\n\n see https://github.com/tauri-apps/tauri/issues/5250#issuecomment-2569380578",
+          "anyOf": [
+            {
+              "$ref": "#/definitions/BackgroundThrottlingPolicy"
+            },
+            {
+              "type": "null"
+            }
+          ]
         }
       },
       "additionalProperties": false
@@ -948,6 +959,32 @@
         }
       ]
     },
+    "BackgroundThrottlingPolicy": {
+      "description": "Background throttling policy.",
+      "oneOf": [
+        {
+          "description": "A policy where background throttling is disabled",
+          "type": "string",
+          "enum": [
+            "disabled"
+          ]
+        },
+        {
+          "description": "A policy where a web view that’s not in a window fully suspends tasks. This is usually the default behavior in case no policy is set.",
+          "type": "string",
+          "enum": [
+            "suspend"
+          ]
+        },
+        {
+          "description": "A policy where a web view that’s not in a window limits processing, but does not fully suspend tasks.",
+          "type": "string",
+          "enum": [
+            "throttle"
+          ]
+        }
+      ]
+    },
     "SecurityConfig": {
       "description": "Security configuration.\n\n See more: <https://v2.tauri.app/reference/config/#securityconfig>",
       "type": "object",

crates/tauri-cli/config.schema.json

@@ -465,6 +465,15 @@
           "description": "Whether page zooming by hotkeys is enabled\n\n ## Platform-specific:\n\n - **Windows**: Controls WebView2's [`IsZoomControlEnabled`](https://learn.microsoft.com/en-us/microsoft-edge/webview2/reference/winrt/microsoft_web_webview2_core/corewebview2settings?view=webview2-winrt-1.0.2420.47#iszoomcontrolenabled) setting.\n - **MacOS / Linux**: Injects a polyfill that zooms in and out with `ctrl/command` + `-/=`,\n 20% in each step, ranging from 20% to 1000%. Requires `webview:allow-set-webview-zoom` permission\n\n - **Android / iOS**: Unsupported.",
           "default": false,
           "type": "boolean"
+        },
+        "backgroundThrottling": {
+          "description": "Change the default background throttling behaviour.\n\n By default, browsers use a suspend policy that will throttle timers and even unload\n the whole tab (view) to free resources after roughly 5 minutes when a view became\n minimized or hidden. This will pause all tasks until the documents visibility state\n changes back from hidden to visible by bringing the view back to the foreground.\n\n ## Platform-specific\n\n - **Linux / Windows / Android**: Unsupported. Workarounds like a pending WebLock transaction might suffice.\n - **iOS**: Supported since version 17.0+.\n - **macOS**: Supported since version 14.0+.\n\n see https://github.com/tauri-apps/tauri/issues/5250#issuecomment-2569380578",
+          "type": "string",
+          "enum": [
+            "disabled",
+            "throttle",
+            "suspend"
+          ]
         }
       },
       "additionalProperties": false

crates/tauri-cli/schema.json

@@ -465,6 +465,15 @@
           "description": "Whether page zooming by hotkeys is enabled\n\n ## Platform-specific:\n\n - **Windows**: Controls WebView2's [`IsZoomControlEnabled`](https://learn.microsoft.com/en-us/microsoft-edge/webview2/reference/winrt/microsoft_web_webview2_core/corewebview2settings?view=webview2-winrt-1.0.2420.47#iszoomcontrolenabled) setting.\n - **MacOS / Linux**: Injects a polyfill that zooms in and out with `ctrl/command` + `-/=`,\n 20% in each step, ranging from 20% to 1000%. Requires `webview:allow-set-webview-zoom` permission\n\n - **Android / iOS**: Unsupported.",
           "default": false,
           "type": "boolean"
+        },
+        "backgroundThrottling": {
+          "description": "Change the default background throttling behaviour.\n\n By default, browsers use a suspend policy that will throttle timers and even unload\n the whole tab (view) to free resources after roughly 5 minutes when a view became\n minimized or hidden. This will pause all tasks until the documents visibility state\n changes back from hidden to visible by bringing the view back to the foreground.\n\n ## Platform-specific\n\n - **Linux / Windows / Android**: Unsupported. Workarounds like a pending WebLock transaction might suffice.\n - **iOS**: Supported since version 17.0+.\n - **macOS**: Supported since version 14.0+.\n\n see https://github.com/tauri-apps/tauri/issues/5250#issuecomment-2569380578",
+          "type": "string",
+          "enum": [
+            "disabled",
+            "throttle",
+            "suspend"
+          ]
         }
       },
       "additionalProperties": false
@@ -2995,4 +3004,4 @@
       "additionalProperties": true
     }
   }
-}
+}

crates/tauri-cli/tauri.config.schema.json

@@ -17,7 +17,7 @@ rustc-args = ["--cfg", "docsrs"]
 rustdoc-args = ["--cfg", "docsrs"]
 
 [dependencies]
-wry = { version = "0.48", default-features = false, features = [
+wry = { version = "0.48.1", default-features = false, features = [
   "drag-drop",
   "protocol",
   "os-webview",

crates/tauri-runtime-wry/Cargo.toml

@@ -4187,6 +4187,20 @@ fn create_webview<T: UserEvent>(
     webview_builder = webview_builder.with_https_scheme(webview_attributes.use_https_scheme);
   }
 
+  if let Some(background_throttling) = webview_attributes.background_throttling {
+    webview_builder = webview_builder.with_background_throttling(match background_throttling {
+      tauri_utils::config::BackgroundThrottlingPolicy::Disabled => {
+        wry::BackgroundThrottlingPolicy::Disabled
+      }
+      tauri_utils::config::BackgroundThrottlingPolicy::Suspend => {
+        wry::BackgroundThrottlingPolicy::Suspend
+      }
+      tauri_utils::config::BackgroundThrottlingPolicy::Throttle => {
+        wry::BackgroundThrottlingPolicy::Throttle
+      }
+    });
+  }
+
   if let Some(color) = webview_attributes.background_color {
     webview_builder = webview_builder.with_background_color(color.into());
   }

crates/tauri-runtime-wry/src/lib.rs

@@ -7,7 +7,9 @@
 use crate::{window::is_label_valid, Rect, Runtime, UserEvent};
 
 use http::Request;
-use tauri_utils::config::{Color, WebviewUrl, WindowConfig, WindowEffectsConfig};
+use tauri_utils::config::{
+  BackgroundThrottlingPolicy, Color, WebviewUrl, WindowConfig, WindowEffectsConfig,
+};
 use url::Url;
 
 use std::{
@@ -215,6 +217,7 @@ pub struct WebviewAttributes {
   pub use_https_scheme: bool,
   pub devtools: Option<bool>,
   pub background_color: Option<Color>,
+  pub background_throttling: Option<BackgroundThrottlingPolicy>,
 }
 
 impl From<&WindowConfig> for WebviewAttributes {
@@ -225,7 +228,9 @@ impl From<&WindowConfig> for WebviewAttributes {
       .zoom_hotkeys_enabled(config.zoom_hotkeys_enabled)
       .use_https_scheme(config.use_https_scheme)
       .browser_extensions_enabled(config.browser_extensions_enabled)
+      .background_throttling(config.background_throttling.clone())
       .devtools(config.devtools);
+
     #[cfg(any(not(target_os = "macos"), feature = "macos-private-api"))]
     {
       builder = builder.transparent(config.transparent);
@@ -279,6 +284,7 @@ impl WebviewAttributes {
       use_https_scheme: false,
       devtools: None,
       background_color: None,
+      background_throttling: None,
     }
   }
 
@@ -444,6 +450,26 @@ impl WebviewAttributes {
     self.background_color = Some(color);
     self
   }
+
+  /// Change the default background throttling behaviour.
+  ///
+  /// By default, browsers use a suspend policy that will throttle timers and even unload
+  /// the whole tab (view) to free resources after roughly 5 minutes when a view became
+  /// minimized or hidden. This will pause all tasks until the documents visibility state
+  /// changes back from hidden to visible by bringing the view back to the foreground.
+  ///
+  /// ## Platform-specific
+  ///
+  /// - **Linux / Windows / Android**: Unsupported. Workarounds like a pending WebLock transaction might suffice.
+  /// - **iOS**: Supported since version 17.0+.
+  /// - **macOS**: Supported since version 14.0+.
+  ///
+  /// see https://github.com/tauri-apps/tauri/issues/5250#issuecomment-2569380578
+  #[must_use]
+  pub fn background_throttling(mut self, policy: Option<BackgroundThrottlingPolicy>) -> Self {
+    self.background_throttling = policy;
+    self
+  }
 }
 
 /// IPC handler.

crates/tauri-runtime/src/webview.rs

@@ -516,6 +516,17 @@
               "type": "null"
             }
           ]
+        },
+        "backgroundThrottling": {
+          "description": "Change the default background throttling behaviour.\n\n By default, browsers use a suspend policy that will throttle timers and even unload\n the whole tab (view) to free resources after roughly 5 minutes when a view became\n minimized or hidden. This will pause all tasks until the documents visibility state\n changes back from hidden to visible by bringing the view back to the foreground.\n\n ## Platform-specific\n\n - **Linux / Windows / Android**: Unsupported. Workarounds like a pending WebLock transaction might suffice.\n - **iOS**: Supported since version 17.0+.\n - **macOS**: Supported since version 14.0+.\n\n see https://github.com/tauri-apps/tauri/issues/5250#issuecomment-2569380578",
+          "anyOf": [
+            {
+              "$ref": "#/definitions/BackgroundThrottlingPolicy"
+            },
+            {
+              "type": "null"
+            }
+          ]
         }
       },
       "additionalProperties": false
@@ -948,6 +959,32 @@
         }
       ]
     },
+    "BackgroundThrottlingPolicy": {
+      "description": "Background throttling policy.",
+      "oneOf": [
+        {
+          "description": "A policy where background throttling is disabled",
+          "type": "string",
+          "enum": [
+            "disabled"
+          ]
+        },
+        {
+          "description": "A policy where a web view that’s not in a window fully suspends tasks. This is usually the default behavior in case no policy is set.",
+          "type": "string",
+          "enum": [
+            "suspend"
+          ]
+        },
+        {
+          "description": "A policy where a web view that’s not in a window limits processing, but does not fully suspend tasks.",
+          "type": "string",
+          "enum": [
+            "throttle"
+          ]
+        }
+      ]
+    },
     "SecurityConfig": {
       "description": "Security configuration.\n\n See more: <https://v2.tauri.app/reference/config/#securityconfig>",
       "type": "object",

crates/tauri-schema-generator/schemas/config.schema.json

@@ -1420,6 +1420,19 @@ impl schemars::JsonSchema for Color {
   }
 }
 
+/// Background throttling policy.
+#[derive(Debug, PartialEq, Eq, Clone, Deserialize, Serialize)]
+#[cfg_attr(feature = "schema", derive(JsonSchema))]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub enum BackgroundThrottlingPolicy {
+  /// A policy where background throttling is disabled
+  Disabled,
+  /// A policy where a web view that’s not in a window fully suspends tasks. This is usually the default behavior in case no policy is set.
+  Suspend,
+  /// A policy where a web view that’s not in a window limits processing, but does not fully suspend tasks.
+  Throttle,
+}
+
 /// The window effects configuration object
 #[skip_serializing_none]
 #[derive(Debug, PartialEq, Clone, Deserialize, Serialize, Default)]
@@ -1687,6 +1700,23 @@ pub struct WindowConfig {
   /// - **Windows**: On Windows 8 and newer, if alpha channel is not `0`, it will be ignored for the webview layer.
   #[serde(alias = "background-color")]
   pub background_color: Option<Color>,
+
+  /// Change the default background throttling behaviour.
+  ///
+  /// By default, browsers use a suspend policy that will throttle timers and even unload
+  /// the whole tab (view) to free resources after roughly 5 minutes when a view became
+  /// minimized or hidden. This will pause all tasks until the documents visibility state
+  /// changes back from hidden to visible by bringing the view back to the foreground.
+  ///
+  /// ## Platform-specific
+  ///
+  /// - **Linux / Windows / Android**: Unsupported. Workarounds like a pending WebLock transaction might suffice.
+  /// - **iOS**: Supported since version 17.0+.
+  /// - **macOS**: Supported since version 14.0+.
+  ///
+  /// see https://github.com/tauri-apps/tauri/issues/5250#issuecomment-2569380578
+  #[serde(default, alias = "background-throttling")]
+  pub background_throttling: Option<BackgroundThrottlingPolicy>,
 }
 
 impl Default for WindowConfig {
@@ -1739,6 +1769,7 @@ impl Default for WindowConfig {
       use_https_scheme: false,
       devtools: None,
       background_color: None,
+      background_throttling: None,
     }
   }
 }
@@ -2858,6 +2889,17 @@ mod build {
     }
   }
 
+  impl ToTokens for BackgroundThrottlingPolicy {
+    fn to_tokens(&self, tokens: &mut TokenStream) {
+      let prefix = quote! { ::tauri::utils::config::BackgroundThrottlingPolicy };
+      tokens.append_all(match self {
+        Self::Disabled => quote! { #prefix::Disabled },
+        Self::Throttle => quote! { #prefix::Throttle },
+        Self::Suspend => quote! { #prefix::Suspend },
+      })
+    }
+  }
+
   impl ToTokens for crate::Theme {
     fn to_tokens(&self, tokens: &mut TokenStream) {
       let prefix = quote! { ::tauri::utils::Theme };
@@ -3004,6 +3046,7 @@ mod build {
       let use_https_scheme = self.use_https_scheme;
       let devtools = opt_lit(self.devtools.as_ref());
       let background_color = opt_lit(self.background_color.as_ref());
+      let background_throttling = opt_lit(self.background_throttling.as_ref());
 
       literal_struct!(
         tokens,
@@ -3054,7 +3097,8 @@ mod build {
         browser_extensions_enabled,
         use_https_scheme,
         devtools,
-        background_color
+        background_color,
+        background_throttling
       );
     }
   }

crates/tauri-utils/src/config.rs

@@ -23,7 +23,7 @@ use tauri_runtime::{
   WebviewDispatch,
 };
 pub use tauri_utils::config::Color;
-use tauri_utils::config::{WebviewUrl, WindowConfig};
+use tauri_utils::config::{BackgroundThrottlingPolicy, WebviewUrl, WindowConfig};
 pub use url::Url;
 
 use crate::{
@@ -867,6 +867,26 @@ fn main() {
     self.webview_attributes.background_color = Some(color);
     self
   }
+
+  /// Change the default background throttling behaviour.
+  ///
+  /// By default, browsers use a suspend policy that will throttle timers and even unload
+  /// the whole tab (view) to free resources after roughly 5 minutes when a view became
+  /// minimized or hidden. This will pause all tasks until the documents visibility state
+  /// changes back from hidden to visible by bringing the view back to the foreground.
+  ///
+  /// ## Platform-specific
+  ///
+  /// - **Linux / Windows / Android**: Unsupported. Workarounds like a pending WebLock transaction might suffice.
+  /// - **iOS**: Supported since version 17.0+.
+  /// - **macOS**: Supported since version 14.0+.
+  ///
+  /// see https://github.com/tauri-apps/tauri/issues/5250#issuecomment-2569380578
+  #[must_use]
+  pub fn background_throttling(mut self, policy: BackgroundThrottlingPolicy) -> Self {
+    self.webview_attributes.background_throttling = Some(policy);
+    self
+  }
 }
 
 /// Webview.