Add spec: Throttling Control - Script #4156

lflores-ms · 2023-11-10T21:26:04Z

Adds spec for Throttling Control (script) API.

specs/ThrottlingControlScript.md

lflores-ms · 2023-11-10T22:03:10Z

specs/ThrottlingControlScript.md

+  /// JavaScript tasks (`setTimeout` and `setInterval`), for the given
+  /// throttling category. 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 default interval values are constants determined by the running


Clarified meaning of "determined by the WebView2 runtime".

specs/ThrottlingControlScript.md

david-risney · 2023-11-10T22:13:10Z

specs/ThrottlingControlScript.md

+  /// throttling scenarios, or match the default background value (usually 1000
+  /// ms). 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 no


Suggested change

/// resource and platform limitations. Setting a value of `0` means no

/// resource and platform limitations. Setting a value of `0` means a preference of no throttling be applied.

david-risney · 2023-11-10T23:01:20Z

specs/ThrottlingControlScript.md

+
+        [interface_name("Microsoft.Web.WebView2.Core.ICoreWebView2_21")]
+        {
+            UInt32 GetThrottlingIntervalPreference(CoreWebView2ThrottlingCategory category);


I'm wondering if instead of two methods on the CoreWebView2, we should make this four get/set properties on the CoreWebView2Settings.

Reading through your document it doesn't seem like its useful to have a method that takes this as an enum because the caller will always be explicitly changing the value of a specific category. In which case its probably easier to have individual properties for each category rather than a method where you choose the category.

And then the whole scenario seems very uncommon so rather than put this on the CoreWebView2 we can move it at least to the CoreWebView2Settings.

What do you think?

I have no strong opinion on whether to put these in CoreWebView2 or CoreWebView2Settings. Looking through our existing APIs, I see that there are properties in the settings object which are applied immediately, so I think we can use the same pattern here.

For enum vs methods. I don't have a strong preference either, but I'm not sure I understand the reasoning:

the caller will always be explicitly changing the value of a specific category

isn't this what we do for other APIs taking non-flags enum types?
Only thing is I think the enum makes it easier to find what the possible/configurable states are.

So this is what it would look like moving as properties to CoreWebView2Settings. Is this what you are suggesting?

namespace Microsoft.Web.WebView2.Core { runtimeclass CoreWebView2Settings { // ... UInt32 ForegroundThrottlingIntervalPreference { get; set; } UInt32 BackgroundThrottlingIntervalPreference { get; set; } UInt32 IntensiveThrottlingIntervalPreference { get; set; } UInt32 IsolatedThrottlingIntervalPreference { get; set; } } runtimeclass CoreWebView2Frame { // ... Boolean ShouldUseIsolatedThrottling { get; set; }; } }

Undecided on the name pattern though. I think we'd want them to show up together so maybe the pattern should be something like ThrottlingIntervalPreference<category> instead?

Giving them the same prefix does help group them although the name is less readable. Let's try that in the API review and see what they say

Just pushed the update moving to properties in settings object. Thanks!

kmahone · 2023-11-16T18:26:41Z

specs/ThrottlingControlScript.md

+
+        [interface_name("Microsoft.Web.WebView2.Core.ICoreWebView2Settings9")]
+        {
+            UInt32 ThrottlingIntervalPreferenceForeground { get; set; };


If these are all values in milliseconds, we should communicate that through the api. Either by the name of the api or by changing the type from UInt32 to something like TimeSpan.

Since you also ship a pure COM api in addition to the WinRT api, the TimeSpan type might not be available (I'm not sure).

Consider a name such as:

ThrottlingIntervalPreferenceInMillisecondsForeground

For review discussion
I'm not aware of an available COM TimeSpan-equivalent type. I can think of the following options:

Keep current name pattern. There's likely precedent in CoreWebView2Notification.TimeStamp. Other TimeStamp APIs in Webview2 do put units in docs rather than the name: CoreWebView2Texture.TimeStamp (microseconds)

Use "Milliseconds" in the name. For discussion -- which position and whether to use "Milliseconds" or "InMilliseconds": PreferredThrottlingInterval<1>Foreground<2>

In either case, we can keep UInt32 in COM and expose as TimeSpan in .NET/WinRT.

InMilliseconds as a suffix

COM: UInt32 InMilliseconds
.NET/WinRT TimeSpan no explicit suffix

kmahone · 2023-11-16T18:32:35Z

specs/ThrottlingControlScript.md

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


It might be helpful to elaborate a bit on what 'throttling' means in this case. If I set a throttling interval of 500ms, that means that timers will file at most once every 500ms - is that correct?

Especially because the Chromium docs call out two stages of throttling.

Stage 1: Timers run at normal speed for X seconds.
Stage 2: After X seconds, timers run at maximum speed Y.

It may not be clear whether this setting controls X or Y. I think it controls Y.

This paragraph is for API review only. Proper documentation for "throttling" meaning is in the API:

/// The preferred wake up interval (in milliseconds) to use for throttleable /// JavaScript tasks (`setTimeout` and `setInterval`) [...] /// A wake up interval is the amount of time that needs to pass before the /// WebView2 Runtime checks for new timer tasks to run. /// [...] [propget] HRESULT ThrottlingIntervalPreferenceForeground([out, retval] UINT32* value);

I can use similar wording to the question above in the "For example" portion of the docs:

If I set a throttling interval of 500ms, that means that timers will file at most once every 500ms

/// 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). **In this case, timers will file at most once every 30ms.**

The two stages of throttling from the referred document map as follows:

X -> ThrottlingIntervalPreferenceForeground

Y -> ThrottlingIntervalPreferenceBackground

there's a third state: ThrottlingIntervalPreferenceIntensive

Please update docs. See discussion later on for changing name to be clearer.

kmahone · 2023-11-16T18:47:08Z

specs/ThrottlingControlScript.md

+
+## Throttle timers in hosted iframes
+
+Throttling Control APIs allow you to throttle timers in specific frames within


So every frame is either a 'regular' frame or an 'isolated' frame. Regular frames are controlled by ThrottlingIntervalPreferenceForeground/ThrottlingIntervalPreferenceBackground/ThrottlingIntervalPreferenceIntensive. Isolated frames are controlled by ThrottlingIntervalPreferenceIsolated.

Is there a reason why an isolated frame does not have Foreground/Background/Intensive properties? Or is that not an interesting scenario?

Valid question - Mostly not an interesting enough scenario to add the complexity. The primary use-case here is an app embedding 3rd party content and wanting to be able to independently limit the performance impact of it. Generally that's something like "low battery, throttle more" or "giving the frame N seconds to run some logic, throttle less".

The case where they'd want to put it in an isolated group while still managing foreground/background/intensive independently of the non-isolated timers would be a niche of a niche that even our most micromanage-y apps wouldn't want that granularity.

So this value takes precedence over the other values?

Update sample to set isolated to at least match background to help demonstrate intended scenario / usage of isolated. Use Andy's comment to update the sample code.

Other names to consider:

Custom

Alternate

Override

Use the following:
PreferredOverrideTimerWakeIntervalInMilliseconds
UseOverrideTimerWakeInterval

lflores-ms · 2023-11-16T21:38:46Z

specs/ThrottlingControlScript.md

+```C#
+namespace Microsoft.Web.WebView2.Core
+{
+    runtimeclass CoreWebView2


Note: class here should be CoreWebView2Settings, matching the COM API above.

Please fix!

FrankC-msft · 2023-11-20T02:40:36Z

specs/ThrottlingControlScript.md

+  /// 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).


Suggested change

/// [Intensive throttling of Javascript timer wake ups](https://chromestatus.com/feature/4718288976216064).

/// [Intensive throttling of JavaScript timer wake ups](https://chromestatus.com/feature/4718288976216064).

nit, capitalization on this instance of JavaScript

This is from the title of the linked document, so I'd lean towards keeping current casing.

Leave as is.

FrankC-msft · 2023-11-20T02:46:18Z

specs/ThrottlingControlScript.md

+consume less resources, for example, when the user is not interactive.
+
+```c#
+void OnNoUserInteraction()


This looks like an event callback, but it is implied business logic of the sample app, not something rooted in the wv2 API surface, correct? Is there a prescribed way app should determine when the customer isn't "interactive"? (Or, is this concept already present in our samples elsewhere?)

No prescribed way to implement detection logic, this is up to the app.

Please add a comment to make it clear how the app would call this method.
A comment like 'the sample app calls this when ... but you might consider doing this in these cases ...'.
Follow up if we want to improve sample code to demonstrate how to actually do this - if we determine this is a common thing that will be helpful.

FrankC-msft · 2023-11-20T03:01:58Z

specs/ThrottlingControlScript.md

+void OnNoUserInteraction()
+{
+    // User is not interactive, keep webview visible but throttle timers to 500ms.
+    webView.CoreWebView2.Settings.ThrottlingIntervalPreferenceForeground = 500;


Do we have precedence for wv2 intervals implicitly being milliseconds? I was going to propose including this in the property names, but realized we're aligning to JS' global functions that already do this. I didn't quickly find an existing webview2-related milliseconds property to check.

(Closest was bufferUsageReportingInterval, so maybe this is OK?)

See comment above on "Milliseconds": #4156 (comment)

See that comment for resolution.

FrankC-msft · 2023-11-20T03:09:16Z

specs/ThrottlingControlScript.md

+  /// 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


It looks like we're missing a way to return to the WebView2 Runtime's default value. (In other words, there's no input for "I don't have a preference" for any of these properties?) I might expect preference=0 means I don't have any preference, but instead it means I prefer zero throttling.

Best case, the constant determined by the running version of the WebView2 Runtime is fixed, and my app can save it before overriding if I'd care about restoring it to 'default'?

Suggested change

/// throttling to be applied. The default value is a constant determined by

/// throttling to be applied. The default value is determined by

I would simplify the text to say that the default value is determined by the runtime. Don't over-promise that it's a constant. It might be determined dynamically (one value if on AC, another if on battery, and another if in energy saver mode).

It seems that the only way to restore default behavior is to save the old value and set it back, and hope that there is no dynamic throttling.

Yes, this is a known limitation and the only solution in current design is to save the value before changes. The intention behind this was to keep the API simpler, but if this is semantically meaningful, I can think of two options:

option 1

add toggle - e.g., CoreWebView2Settings.IsThrottlingEnabled

under current pattern, it would be 4 additional properties

alternatively, we can bring back the "throttling category" enum and use for both interval and toggle

make 0 reset to default

option 2

make 0 reset to default

make 1-4 mean off

due to architectural reasons, there's always an effective minimum 4 ms throttling (even when throttling is off)

none (current)

save value before changing, then restore

... or a reversal of option 1? (method for reset and keep 0 meaning off) I think option 1 is better than its reversal.

Prefer the 'simpler' option: save value before changing then restore - no new API changes.

FrankC-msft · 2023-11-20T03:17:56Z

specs/ThrottlingControlScript.md

+  [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


This Interval Preference is unique among the four, in that it applies to frame hosted content instead of this WebView's direct content. Maybe worth differentiating e.g. ThrottlingIntervalPreferenceIsolatedFrames

For review discussion
I agree and intent to update the name unless there's a different outcome during review.

FrankC-msft · 2023-11-20T03:19:35Z

specs/ThrottlingControlScript.md

+  [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


All isolated Frames are subject to the same throttling preference? (I infer there's just little value in being able to throttle isolated frames to different intervals. Is that right?)

Yes, please make explicit in ref docs.

FrankC-msft · 2023-11-20T03:21:52Z

specs/ThrottlingControlScript.md

+
+  /// 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


An alternate design appears to be one uint32 property on CoreWebView2Frame, instead of a pair uint32 + Boolean properties to set the interval value and opt-in to applying it. Fewer properties to manage are often better. Was it discussed whether grouping this near the other IntervalPreferences is higher value in this case?

Alternative design options are limited by the Chromium architecture for throttling. While it's likely technically feasible to override individual frame intervals, a change like this would mean significantly more implementation complexity and risk. This was discussed during original design of the API, but we didn't identify a strong need for it, so we landed on a compromise of "isolated" interval + per-frame opt in.

If you have a scenario that strongly requires per-frame interval, please feel free to share in this review, or reach out to us through email.

Existing API surface better matches intended scenario. Leave as is.

FrankC-msft · 2023-11-20T03:24:58Z

specs/ThrottlingControlScript.md

+[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


"Should" suggests application preference. Are there any cases where the Boolean won't match whether IntervalPreferenceIsolated is being used? Documentation suggests this is fully IsUsingThrottlingIntervalPreferenceIsolated. (or a shorter name that is as definite.)

Rename Should -> UseOverrideTimerWakeInterval

oldnewthing · 2023-11-21T18:40:38Z

specs/ThrottlingControlScript.md

+    // Unthrottle background timers.
+    webView.CoreWebView2.Settings.ThrottlingIntervalPreferenceBackground = 0;
+    // Effectively disable intensive throttling by overriding its timer interval.
+    webView.CoreWebView2.Settings.ThrottlingIntervalPreferenceIntensive = 0;


Noting that "intensive" is the public name Chromium has given to this feature.

oldnewthing · 2023-11-21T18:47:26Z

specs/ThrottlingControlScript.md

+void OnNoUserInteraction()
+{
+    // User is not interactive, keep webview visible but throttle timers to 500ms.
+    webView.CoreWebView2.Settings.ThrottlingIntervalPreferenceForeground = 500;


There are multiple types of throttling in Chromium. Timer throttling. Network throttling. Tab throttling. Extension throttling. CPU throttling. Authentication throttling.

From its name, it is not clear which of the many types of throttling this setting controls.

TimerThrottlingPreference(Foreground|Background|Intensive|Isolated)?

Or, for grammar,

(Foreground|Background|Intensive|Isolated)TimerThrottlingInterval?

Or if we really need to emphasize that this is a preference that may not be honored

Preferred(Foreground|Background|Intensive|Isolated)TimerThrottlingInterval?

Even the term "interval" is ambiguous. Is this the interval between throttlings? (No, it's the interval of the timer.)

Other parts of the documentation call this the "wake-up" interval.

Preferred(Foreground|Background|Intensive|Isolated)TimerWakeInterval?

Please use Preferred(Foreground|Background|Intensive|Isolated)TimerWakeInterval(InMilliseconds) (InMilliseconds only for COM)

oldnewthing · 2023-11-21T19:03:00Z

specs/ThrottlingControlScript.md

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


Especially because the Chromium docs call out two stages of throttling.

Stage 1: Timers run at normal speed for X seconds.
Stage 2: After X seconds, timers run at maximum speed Y.

It may not be clear whether this setting controls X or Y. I think it controls Y.

oldnewthing · 2023-11-21T19:06:39Z

specs/ThrottlingControlScript.md

+    webView.Visibility = System.Windows.Visibility.Hidden;
+}
+
+void DisableHiddenWebViewCore()


This method name is confusing. The name says that it's disabling the hidden webview, but really it's showing the webview and setting new values.

Is this code trying to restore defaults? If so, it should save the previous values of the properties in SetupHiddenWebViewCore so that it can restore them here, rather than hard-coding what it believes to be the defaults.

Name is sort of double negative. Better would be Hide/ShowWebView
If we're trying to undo previous changes back to previous values, we should be saving those values or showing how to do this properly.

oldnewthing · 2023-11-21T19:13:14Z

specs/ThrottlingControlScript.md

+  /// 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


Suggested change

/// throttling to be applied. The default value is a constant determined by

/// throttling to be applied. The default value is determined by

I would simplify the text to say that the default value is determined by the runtime. Don't over-promise that it's a constant. It might be determined dynamically (one value if on AC, another if on battery, and another if in energy saver mode).

It seems that the only way to restore default behavior is to save the old value and set it back, and hope that there is no dynamic throttling.

oldnewthing · 2023-11-21T19:49:20Z

specs/ThrottlingControlScript.md

+  [propget] HRESULT ShouldUseIsolatedThrottling([out, retval] BOOL* value);
+
+  /// Sets the `ShouldUseIsolatedThrottling` property.
+  [propput] HRESULT ShouldUseIsolatedThrottling([in] BOOL value);


If we add other types of throttling (network, etc.), will this flag also opt into isolated network throttling etc? Or is this only for timer throttling?

New name fixes this. See above.

oldnewthing · 2023-11-21T19:56:08Z

specs/ThrottlingControlScript.md

+void OnNoUserInteraction()
+{
+    // User is not interactive, keep webview visible but throttle timers to 500ms.
+    webView.CoreWebView2.Settings.ThrottlingIntervalPreferenceForeground = 500;


Note that the term "Foreground" here does not refer to Win32 "foreground" (receives keyboard input) but rather the Chromium concept of "foreground" which just means "programmatically visible". And even a programmatically visible that is completely occluded (so not visible to the end user) counts as "foreground".

Is this web-centric definition of "foreground" already established in WebView2-land?

This is a different kind of foreground defined in MDN: https://developer.mozilla.org/en-US/docs/Web/API/Page_Visibility_API.

Please include definition and link in our docs.

oldnewthing · 2023-11-21T19:57:28Z

specs/ThrottlingControlScript.md

+
+    // User is not interactive, keep webview visible but throttle timers to
+    // 500ms.
+    CHECK_FAILURE(settings2->put_ThrottlingIntervalPreferenceForeground(500));


When do these changes take effect? According to the documentation, all Settings properties take effect at the next top-level navigation, with two explicit exceptions that take effect immediately.

Takes effect immediately. Will update the docs to state that.

Please make explicit in our documentation.

oldnewthing · 2023-11-21T19:58:56Z

specs/ThrottlingControlScript.md

+    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;


If we want the throttling changes to take effect immediately, do we need to do a fake "navigate to self"? (Though that would destroy any page state, so maybe not?)

n/a see above

oldnewthing · 2023-11-21T19:59:45Z

specs/ThrottlingControlScript.md

+    {
+        if (args.Frame.Name == "isolated")
+        {
+            args.Frame.ShouldUseIsolatedThrottling = true;


When does this setting take effect? Immediately? On next frame navigation? Is setting it in FrameCreated "soon enough"?

Takes effect immediately. FrameCreated is the first chance to set the property as this is when we get the CoreWebView2Frame object.

lflores-ms · 2023-11-21T20:07:51Z

specs/ThrottlingControlScript.md

+  /// (usually 1000 ms).
+  [propget] HRESULT ThrottlingIntervalPreferenceForeground([out, retval] UINT32* value);
+  /// Sets the `ThrottlingIntervalPreferenceForeground` property.
+  [propput] HRESULT ThrottlingIntervalPreferenceForeground([in] UINT32 value);


Naming of these properties should follow pattern of existing WebView2 APIs, using "Preferred" as prefix:

PreferredColorScheme

PreferredTrackingPreventionLevel

sschalek · 2023-11-21T20:12:47Z

specs/ThrottlingControlScript.md

+    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;


Does the hosted JS know that it is invisible but there is a desire for it to still run in this state? Or would this info have to come through a different channel, or is the expectation that hosted code will always try to run if it can and won't itself, say, stop regular updates or communication with its backing service if the web platform says it's not visible?

Another way of putting it is, how is "visible as far as the web platform is concerned" differentiated from "host app has set the WV2 element to be visible" from "content is actually visible" both from the perspective of the host app calling these APIs and the hosted code having access to the web platform APIs?

JavaScript context only has knowledge of "visible as far as the web platform is concerned" through Page Visibility API.

From the host app side, this is controlled by CoreWebView2Controller.IsVisible property. For WebView2 controls in .NET/WinRT, IsVisible property is controlled directly by the framework and tied to actual user visibility. The hosted JavaScript has no knowledge of this through its Web Platform API, but if needed, can be informed by the host through window.chrome.webview object.

Consider adding explicit end to end description of how API fits into chromium/web platform feature to the ref docs and examples of how an end dev might use it

MikeHillberg · 2023-11-21T20:28:01Z

specs/ThrottlingControlScript.md

+  /// foreground state. A WebView is in foreground state when its `IsVisible`
+  /// property is `TRUE`.


Is this name mapping "visible" to "foreground" standard terminology? Otherwise, calling this ThrottlingIntervalPreferenceWhenVisible would be easier to understand

Also PreferredThrottlingInterval... rather than ThrottlingIntervalPreference....

MikeHillberg · 2023-11-21T20:46:56Z

specs/ThrottlingControlScript.md

+void OnUserInteraction()
+{
+    // User is interactive again, unthrottle foreground timers.
+    webView.CoreWebView2.Settings.ThrottlingIntervalPreferenceForeground = 0;


Reading this sample, I though it was reverting OnNoUserInteraction, but it's actually putting it into a third mode.

Update comment to make it clear if we're going to default value or not. (Confusion if this is supposed to be default value or 0). And consider updating sample code to show how to go to default value.

MikeHillberg · 2023-11-21T20:48:53Z

specs/ThrottlingControlScript.md

+
+## Throttle timers in hosted iframes
+
+Throttling Control APIs allow you to throttle timers in specific frames within


So this value takes precedence over the other values?

MikeHillberg · 2023-11-21T20:51:56Z

specs/ThrottlingControlScript.md

+  /// 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);


Typing guideline is Int32, unless it's truly necessary to support >2 billion

Please fix.

MikeHillberg · 2023-11-21T20:56:49Z

specs/ThrottlingControlScript.md

+    {
+        if (args.Frame.Name == "isolated")
+        {
+            args.Frame.ShouldUseIsolatedThrottling = true;


Does this affect nested frames? Or does the code need to handle hierarchy in the event handler?

Great question!

Please update ref docs to clearly state it.

Please follow up with PM if we need this to be inherited or not. Alternatively, if grandchild frame event is coming soon then this is less interesting question to answer and not inherit is easier.

MikeHillberg · 2023-11-21T20:59:27Z

specs/ThrottlingControlScript.md

+
+        [interface_name("Microsoft.Web.WebView2.Core.ICoreWebView2Settings9")]
+        {
+            UInt32 ThrottlingIntervalPreferenceForeground { get; set; };


InMilliseconds as a suffix

david-risney · 2023-11-21T21:07:00Z

specs/ThrottlingControlScript.md

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


Please update docs. See discussion later on for changing name to be clearer.

david-risney · 2023-11-21T21:09:23Z

specs/ThrottlingControlScript.md

+consume less resources, for example, when the user is not interactive.
+
+```c#
+void OnNoUserInteraction()


Please add a comment to make it clear how the app would call this method.
A comment like 'the sample app calls this when ... but you might consider doing this in these cases ...'.
Follow up if we want to improve sample code to demonstrate how to actually do this - if we determine this is a common thing that will be helpful.

david-risney · 2023-11-21T21:14:23Z

specs/ThrottlingControlScript.md

+
+        [interface_name("Microsoft.Web.WebView2.Core.ICoreWebView2Settings9")]
+        {
+            UInt32 ThrottlingIntervalPreferenceForeground { get; set; };


COM: UInt32 InMilliseconds
.NET/WinRT TimeSpan no explicit suffix

david-risney · 2023-11-21T21:14:55Z

specs/ThrottlingControlScript.md

+void OnNoUserInteraction()
+{
+    // User is not interactive, keep webview visible but throttle timers to 500ms.
+    webView.CoreWebView2.Settings.ThrottlingIntervalPreferenceForeground = 500;


See that comment for resolution.

david-risney · 2023-11-21T21:18:56Z

specs/ThrottlingControlScript.md

+void OnNoUserInteraction()
+{
+    // User is not interactive, keep webview visible but throttle timers to 500ms.
+    webView.CoreWebView2.Settings.ThrottlingIntervalPreferenceForeground = 500;


Please use Preferred(Foreground|Background|Intensive|Isolated)TimerWakeInterval(InMilliseconds) (InMilliseconds only for COM)

david-risney · 2023-11-21T22:02:03Z

specs/ThrottlingControlScript.md

+
+  /// 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


Existing API surface better matches intended scenario. Leave as is.

david-risney · 2023-11-21T22:02:25Z

specs/ThrottlingControlScript.md

+
+  /// 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


Please update.

david-risney · 2023-11-21T22:04:40Z

specs/ThrottlingControlScript.md

+[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


Rename Should -> UseOverrideTimerWakeInterval

david-risney · 2023-11-21T22:05:21Z

specs/ThrottlingControlScript.md

+  [propget] HRESULT ShouldUseIsolatedThrottling([out, retval] BOOL* value);
+
+  /// Sets the `ShouldUseIsolatedThrottling` property.
+  [propput] HRESULT ShouldUseIsolatedThrottling([in] BOOL value);


New name fixes this. See above.

david-risney · 2023-11-21T22:05:41Z

specs/ThrottlingControlScript.md

+```C#
+namespace Microsoft.Web.WebView2.Core
+{
+    runtimeclass CoreWebView2


Please fix!

lflores-ms added 4 commits November 7, 2023 18:06

Add spec file

03831fb

Add Throttling Control spec baseline draft

84a31c0

Update from ADO PR feedback

bb4deee

Add linebreaks

855667f

lflores-ms requested a review from david-risney November 10, 2023 21:26

lflores-ms commented Nov 10, 2023

View reviewed changes

david-risney requested review from aluhrs13 and vickiez November 10, 2023 22:15

david-risney requested changes Nov 10, 2023

View reviewed changes

lflores-ms added 2 commits November 14, 2023 18:52

PR feedback: rename IsUntrusted->ShouldUseIsolatedThrottling

e6e1466

PR feedback: move throttling preference to settings as properties

a477d20

david-risney approved these changes Nov 15, 2023

View reviewed changes

lflores-ms changed the base branch from spec/throttling-control-script to main November 15, 2023 23:56

david-risney self-requested a review November 15, 2023 23:57

lflores-ms added the API Proposal Review WebView2 API Proposal for review. label Nov 15, 2023

kmahone reviewed Nov 16, 2023

View reviewed changes

lflores-ms commented Nov 16, 2023

View reviewed changes

lflores-ms mentioned this pull request Nov 17, 2023

API Review: Throttling Control - Script MicrosoftEdge/WebView2Announcements#80

Open

FrankC-msft reviewed Nov 20, 2023

View reviewed changes

oldnewthing reviewed Nov 21, 2023

View reviewed changes

lflores-ms commented Nov 21, 2023

View reviewed changes

sschalek reviewed Nov 21, 2023

View reviewed changes

MikeHillberg reviewed Nov 21, 2023

View reviewed changes

david-risney requested changes Nov 21, 2023

View reviewed changes

	/// resource and platform limitations. Setting a value of `0` means no
	/// resource and platform limitations. Setting a value of `0` means a preference of no throttling be applied.


		## Throttle timers in hosted iframes

		Throttling Control APIs allow you to throttle timers in specific frames within

	/// [Intensive throttling of Javascript timer wake ups](https://chromestatus.com/feature/4718288976216064).
	/// [Intensive throttling of JavaScript timer wake ups](https://chromestatus.com/feature/4718288976216064).

	/// throttling to be applied. The default value is a constant determined by
	/// throttling to be applied. The default value is determined by

		/// foreground state. A WebView is in foreground state when its `IsVisible`
		/// property is `TRUE`.

Add spec: Throttling Control - Script #4156

Are you sure you want to change the base?

Add spec: Throttling Control - Script #4156

Conversation

lflores-ms commented Nov 10, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lflores-ms Nov 15, 2023 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lflores-ms Nov 21, 2023 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lflores-ms Nov 21, 2023 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lflores-ms Nov 15, 2023 •

edited

lflores-ms Nov 21, 2023 •

edited

lflores-ms Nov 21, 2023 •

edited