Add spec: Throttling Control - Script

specs/ThrottlingControlScript.md

@@ -0,0 +1,325 @@
+Throttling Control - Script Throttling
+===
+
+# Background
+Web content in WebView2 is generally subject to the same Web Platform
+restrictions as in the Microsoft Edge browser. However, some of the scenarios
+for WebView2 applications differ from the scenarios in the browser. For this
+reason, we're providing a set of APIs to fine-tune performance of scripts
+running in WebView2. These APIs allow WebView2 applications to achieve two
+things:
+
+* Customize script timers (`setTimeout` and `setInterval`) throttling under
+different page states (foreground, background, and background with intensive
+throttling)
+* Throttle script timers in select hosted iframes
+
+# Examples
+
+## Throttle timers in visible WebView
+
+Throttling Control APIs allow you to throttle JavaScript timers in scenarios
+where the WebView2 control in your application needs to remain visible, but
+consume less resources, for example, when the user is not interactive.
+
+```c#
+void OnNoUserInteraction()
+{
+    // User is not interactive, keep webview visible but throttle timers to 500ms.
+    webView.CoreWebView2.Settings.ThrottlingIntervalPreferenceForeground = 500;
+}
+
+void OnUserInteraction()
+{
+    // User is interactive again, unthrottle foreground timers.
+    webView.CoreWebView2.Settings.ThrottlingIntervalPreferenceForeground = 0;
+}
+```
+
+```cpp
+void ScenarioThrottlingControl::OnNoUserInteraction()
+{
+    wil::com_ptr<ICoreWebView2Settings> settings;
+    m_webview->get_Settings(&settings);
+    auto settings2 = settings.try_query<ICoreWebView2Settings9>();
+    CHECK_FEATURE_RETURN_EMPTY(settings2);
+
+    // User is not interactive, keep webview visible but throttle timers to
+    // 500ms.
+    CHECK_FAILURE(settings2->put_ThrottlingIntervalPreferenceForeground(500));
+}
+
+void ScenarioThrottlingControl::OnUserInteraction()
+{
+    wil::com_ptr<ICoreWebView2Settings> settings;
+    m_webview->get_Settings(&settings);
+    auto settings2 = settings.try_query<ICoreWebView2Settings9>();
+    CHECK_FEATURE_RETURN_EMPTY(settings2);
+
+    // User is interactive again, unthrottle foreground timers.
+    CHECK_FAILURE(settings2->put_ThrottlingIntervalPreferenceForeground(0));
+}
+```
+
+## Unthrottle timers in hidden WebView
+
+Throttling Control APIs allow you to set a custom throttling interval for timers
+on hidden WebViews. For example, if there's logic in your app that runs in
+JavaScript but doesn't need to render content, you can keep the WebView hidden
+and unthrottle its timers.
+
+```C#
+void SetupHiddenWebViewCore()
+{
+    // This WebView2 will remain hidden but needs to keep running timers.
+    // Unthrottle background timers.
+    webView.CoreWebView2.Settings.ThrottlingIntervalPreferenceBackground = 0;
+    // Effectively disable intensive throttling by overriding its timer interval.
+    webView.CoreWebView2.Settings.ThrottlingIntervalPreferenceIntensive = 0;
+    webView.Visibility = System.Windows.Visibility.Hidden;
+}
+
+void DisableHiddenWebViewCore()
+{
+    webView.Visibility = System.Windows.Visibility.Visible;
+    webView.CoreWebView2.Settings.ThrottlingIntervalPreferenceBackground = 1000;
+    webView.CoreWebView2.Settings.ThrottlingIntervalPreferenceIntensive = 60000;
+}
+```
+
+```cpp
+void ScenarioThrottlingControl::SetupHiddenWebViewCore()
+{
+    wil::com_ptr<ICoreWebView2Settings> settings;
+    m_webview->get_Settings(&settings);
+    auto settings2 = settings.try_query<ICoreWebView2Settings9>();
+    CHECK_FEATURE_RETURN_EMPTY(settings2);
+
+    // This WebView2 will remain hidden but needs to keep running timers.
+    // Unthrottle background timers.
+    CHECK_FAILURE(settings2->put_ThrottlingIntervalPreferenceBackground(0));
+    // Effectively disable intensive throttling by overriding its timer interval.
+    CHECK_FAILURE(settings2->put_ThrottlingIntervalPreferenceIntensive(0));
+
+    CHECK_FAILURE(m_appWindow->GetWebViewController()->put_IsVisible(FALSE));
+}
+
+void ScenarioThrottlingControl::DisableHiddenWebViewCore()
+{
+    CHECK_FAILURE(m_appWindow->GetWebViewController()->put_IsVisible(TRUE));
+
+    wil::com_ptr<ICoreWebView2Settings> settings;
+    m_webview->get_Settings(&settings);
+    auto settings2 = settings.try_query<ICoreWebView2Settings9>();
+    CHECK_FEATURE_RETURN_EMPTY(settings2);
+
+    CHECK_FAILURE(settings2->put_ThrottlingIntervalPreferenceBackground(1000));
+    CHECK_FAILURE(settings2->put_ThrottlingIntervalPreferenceIntensive(60000));
+}
+```
+
+## Throttle timers in hosted iframes
+
+Throttling Control APIs allow you to throttle timers in specific frames within
+the WebView2 control. For example, if your application uses iframes to host 3rd
+party content, you can select and mark these frames to be throttled separately
+from the main frame and other regular, unmarked frames.
+
+```C#
+void SetupIsolatedFramesHandler()
+{
+    // You can use the frame properties to determine whether it should be
+    // marked to be throttled separately from main frame.
+    webView.CoreWebView2.FrameCreated += (sender, args) =>
+    {
+        if (args.Frame.Name == "isolated")
+        {
+            args.Frame.ShouldUseIsolatedThrottling = true;
+        }
+    };
+
+    webView.CoreWebView2.Settings.ThrottlingIntervalPreferenceIsolated = 500;
+}
+```
+
+```cpp
+void ScenarioThrottlingControl::SetupIsolatedFramesHandler()
+{
+    auto webview4 = m_webview.try_query<ICoreWebView2_4>();
+    CHECK_FEATURE_RETURN_EMPTY(webview4);
+
+    // You can use the frame properties to determine whether it should be
+    // marked to be throttled separately from main frame.
+    CHECK_FAILURE(webview4->add_FrameCreated(
+        Callback<ICoreWebView2FrameCreatedEventHandler>(
+            [this](ICoreWebView2* sender, ICoreWebView2FrameCreatedEventArgs* args) -> HRESULT
+            {
+                wil::com_ptr<ICoreWebView2Frame> webviewFrame;
+                CHECK_FAILURE(args->get_Frame(&webviewFrame));
+
+                auto webviewFrame6 =
+                    webviewFrame.try_query<ICoreWebView2Frame6>();
+                CHECK_FEATURE_RETURN_HRESULT(webviewFrame6);
+
+                wil::unique_cotaskmem_string name;
+                CHECK_FAILURE(webviewFrame->get_Name(&name));
+                if (wcscmp(name.get(), L"isolated") == 0)
+                {
+                    CHECK_FAILURE(webviewFrame6->put_ShouldUseIsolatedThrottling(TRUE));
+                }
+
+                return S_OK;
+            })
+            .Get(),
+        &m_frameCreatedToken));
+
+    wil::com_ptr<ICoreWebView2Settings> settings;
+    m_webview->get_Settings(&settings);
+    auto settings2 = settings.try_query<ICoreWebView2Settings9>();
+    CHECK_FAILURE(settings2->put_ThrottlingIntervalPreferenceIsolated(500));
+}
+```
+
+# API Details
+```cpp
+/// A continuation of the `ICoreWebView2Settings` interface to support
+/// ThrottlingPreference.
+[uuid(00f1b5fb-91ed-4722-9404-e0f8fd1e6b0a), object, pointer_default(unique)]
+interface ICoreWebView2Settings9 : ICoreWebView2Settings8 {
+  /// The preferred wake up interval (in milliseconds) to use for throttleable
+  /// JavaScript tasks (`setTimeout` and `setInterval`), when the WebView is in
+  /// foreground state. A WebView is in foreground state when its `IsVisible`
+  /// property is `TRUE`.
+  ///
+  /// A wake up interval is the amount of time that needs to pass before the
+  /// WebView2 Runtime checks for new timer tasks to run.
+  ///
+  /// The WebView2 Runtime will try to respect the preferred interval set by the
+  /// application, but the effective value will be constrained by resource and
+  /// platform limitations. Setting a value of `0` means a preference of no
+  /// throttling to be applied. The default value is a constant determined by
+  /// the running version of the WebView2 Runtime.
+  ///
+  /// For example, an application might use a foreground value of 30 ms for
+  /// moderate throttling scenarios, or match the default background value
+  /// (usually 1000 ms).
+  [propget] HRESULT ThrottlingIntervalPreferenceForeground([out, retval] UINT32* value);
+  /// Sets the `ThrottlingIntervalPreferenceForeground` property.
+  [propput] HRESULT ThrottlingIntervalPreferenceForeground([in] UINT32 value);
+
+  /// The preferred wake up interval (in milliseconds) to use for throttleable
+  /// JavaScript tasks (`setTimeout` and `setInterval`), when the WebView is in
+  /// background state, with no intensive throttling. A WebView is in background
+  /// state when its `IsVisible` property is `FALSE`. Intensive throttling is a
+  /// substate of background state. For more details about intensive throttling,
+  /// see [Intensive throttling of Javascript timer wake ups](https://chromestatus.com/feature/4718288976216064).
+  ///
+  /// A wake up interval is the amount of time that needs to pass before the
+  /// WebView2 Runtime checks for new timer tasks to run.
+  ///
+  /// The WebView2 Runtime will try to respect the preferred interval set by the
+  /// application, but the effective value will be constrained by resource and
+  /// platform limitations. Setting a value of `0` means a preference of no
+  /// throttling to be applied. The default value is a constant determined by
+  /// the running version of the WebView2 Runtime. All other background state
+  /// policies (including intensive throttling) are effective independently of
+  /// this setting.
+  ///
+  /// For example, an application might use a background value of 100 ms to
+  /// relax the default background value (usually 1000 ms).
+  [propget] HRESULT ThrottlingIntervalPreferenceBackground([out, retval] UINT32* value);
+  /// Sets the `ThrottlingIntervalPreferenceBackground` property.
+  [propput] HRESULT ThrottlingIntervalPreferenceBackground([in] UINT32 value);
+
+  /// The preferred wake up interval (in milliseconds) to use for throttleable
+  /// JavaScript tasks (`setTimeout` and `setInterval`), when the WebView is in
+  /// background state with intensive throttling. Intensive throttling is a
+  /// substate of background state. For more details about intensive
+  /// throttling, see
+  /// [Intensive throttling of Javascript timer wake ups](https://chromestatus.com/feature/4718288976216064).
+  ///
+  /// A wake up interval is the amount of time that needs to pass before the
+  /// WebView2 Runtime checks for new timer tasks to run.
+  ///
+  /// The WebView2 Runtime will try to respect the preferred interval set by the
+  /// application, but the effective value will be constrained by resource and
+  /// platform limitations. Setting a value of `0` means a preference of no
+  /// throttling to be applied. The default value is a constant determined by
+  /// the running version of the WebView2 Runtime.
+  [propget] HRESULT ThrottlingIntervalPreferenceIntensive([out, retval] UINT32* value);
+  /// Sets the `ThrottlingIntervalPreferenceIntensive` property.
+  [propput] HRESULT ThrottlingIntervalPreferenceIntensive([in] UINT32 value);
+
+  /// The preferred wake up interval (in milliseconds) to use for throttleable
+  /// JavaScript tasks (`setTimeout` and `setInterval`), in frames whose
+  /// `ShouldUseIsolatedThrottling` property is set to `TRUE`. This is a category
+  /// specific to WebView2 with no corresponding state in the Chromium tab state
+  /// model.
+  ///
+  /// A wake up interval is the amount of time that needs to pass before the
+  /// WebView2 Runtime checks for new timer tasks to run.
+  ///
+  /// The WebView2 Runtime will try to respect the preferred interval set by the
+  /// application, but the effective value will be constrained by resource and
+  /// platform limitations. Setting a value of `0` means a preference of no
+  /// throttling to be applied. The default value is a constant determined by
+  /// the running version of the WebView2 Runtime.
+  ///
+  /// For example, an application might use an isolated throttling value of 30
+  /// ms to reduce resource consumption from third party frames in the WebView.
+  [propget] HRESULT ThrottlingIntervalPreferenceIsolated([out, retval] UINT32* value);
+  /// Sets the `ThrottlingIntervalPreferenceIsolated` property.
+  [propput] HRESULT ThrottlingIntervalPreferenceIsolated([in] UINT32 value);
+}
+
+/// A continuation of the `ICoreWebView2Frame` interface to support
+/// ShouldUseIsolatedThrottling property.
+[uuid(5b7d1b96-699b-44a2-b9f1-b8e88f9ac2be), object, pointer_default(unique)]
+interface ICoreWebView2Frame6 : ICoreWebView2Frame5 {
+  /// Indicates whether the frame has been marked for isolated throttling by the
+  /// host app. When `TRUE`, the frame will receive the throttling interval set
+  /// by `ThrottlingIntervalPreferenceIsolated`. When `FALSE`, and for main
+  /// frame, throttling interval will be determined by page state and the
+  /// interval through their corresponding properties in the
+  /// `CoreWebView2Settings` object. Defaults to `FALSE` unless set otherwise.
+  [propget] HRESULT ShouldUseIsolatedThrottling([out, retval] BOOL* value);
+
+  /// Sets the `ShouldUseIsolatedThrottling` property.
+  [propput] HRESULT ShouldUseIsolatedThrottling([in] BOOL value);
+}
+
+```
+
+```C#
+namespace Microsoft.Web.WebView2.Core
+{
+    runtimeclass CoreWebView2
+    {
+        // ...
+
+        [interface_name("Microsoft.Web.WebView2.Core.ICoreWebView2Settings9")]
+        {
+            UInt32 ThrottlingIntervalPreferenceForeground { get; set; };
+
+            UInt32 ThrottlingIntervalPreferenceBackground { get; set; };
+
+            UInt32 ThrottlingIntervalPreferenceIntensive { get; set; };
+
+            UInt32 ThrottlingIntervalPreferenceIsolated { get; set; };
+        }
+    }
+
+    runtimeclass CoreWebView2Frame
+    {
+        // ...
+
+        [interface_name("Microsoft.Web.WebView2.Core.ICoreWebView2Frame6")]
+        {
+            Boolean ShouldUseIsolatedThrottling { get; set; };
+        }
+    }
+}
+
+```
+
+# Appendix