From 5ed69b68d66e32eb0419c1b4753692fcc8a26f53 Mon Sep 17 00:00:00 2001 From: David Risney Date: Tue, 25 Oct 2022 15:55:07 -0700 Subject: [PATCH 1/3] Create wv2winrt-cacheable-properties.md --- specs/wv2winrt-cacheable-properties.md | 71 ++++++++++++++++++++++++++ 1 file changed, 71 insertions(+) create mode 100644 specs/wv2winrt-cacheable-properties.md diff --git a/specs/wv2winrt-cacheable-properties.md b/specs/wv2winrt-cacheable-properties.md new file mode 100644 index 000000000..c05a8320e --- /dev/null +++ b/specs/wv2winrt-cacheable-properties.md @@ -0,0 +1,71 @@ +wv2winrt Cacheable Properties +=== + +# Background + +WebView2 supports WinRT projection into JavaScript similar to how the previous edgehtml +WebView support WinRT projection. However unlike the previous WebView, for WebView2 the +WinRT objects live in a different process from the JavaScript that invokes the WinRT. +Because of this cross-process access, performance is something we're working on improving. +To that end, this feature allows you to mark individual runtimeclass properties as +cacheable so that the JavaScript running in the renderer process can cache the result of +the property value the first time and avoid subsequent cross-process calls each time the +property is accessed. Working with partner apps with existing JavaScript that uses WinRT +this was identified as something in particular that could help improve runtime +performance. + +# Examples + +```c# (but really MIDL3) + [default_interface] + runtimeclass Toaster + { + // This property changes value throughout the lifetime of the object so is not + // marked readonly. + Boolean Available { get; }; + + // This property has one value for the lifetime of the object so we mark it + // readonly to improve wv2winrt performance. + [corewebview2readonly] + String Model { get; }; + + // ... + } +``` + +# API Details + +```c# (but really MIDL3) +namespace Microsoft.Web.WebView2.Core +{ + /// You can use the CoreWebView2ReadOnly attribute on a runtimeclass property + /// definition in MIDL3 if the property value doesn't change for the lifetime + /// of its object. When an object is projected into JavaScript via + /// `CoreWebView2.AddHostObjectToScript`, WebView2 will cache property values + /// marked with this attribute. This can potentially improve performance by + /// reducing the number of cross-process calls to obtain the latest value of + /// the property. + [attributeusage(target_property)] + [attributename("corewebview2readonly")] + attribute CoreWebView2ReadOnlyAttribute + { + } +} +``` + +# Appendix + +Names considered for the attribute: + * **Cacheable**: Caching is what WebView2 will do with the property rather than describing + an aspect of the runtimeclass property. + * **ReadOnly**: Similar to C#'s readonly keyword which indicates a value won't change (once + initialized). A more familiar term to end developers than 'immutable'. It does + convey that the caller can't set it, but does it also convey that the implementer also + cannot change the value? + * **Immutable**: Perhaps more explicit than readonly that the implementer also cannot + change the value, but perhaps less familiar of a term. + +For the sample code, the only code you have to write is applying the attribute to the +property. The only effect this has is to potentially improve performance so there's no other +code to demonstrate anything. Accordingly, not sure what else to do in the sample code other +than the MIDL3. From 61c83efa70ed965043ff98ffd16a8ae4f5cd3bae Mon Sep 17 00:00:00 2001 From: David Risney Date: Tue, 8 Nov 2022 15:55:27 -0800 Subject: [PATCH 2/3] Update wv2winrt-cacheable-properties.md --- specs/wv2winrt-cacheable-properties.md | 52 +++++++++++++++++--------- 1 file changed, 35 insertions(+), 17 deletions(-) diff --git a/specs/wv2winrt-cacheable-properties.md b/specs/wv2winrt-cacheable-properties.md index c05a8320e..94170e9f9 100644 --- a/specs/wv2winrt-cacheable-properties.md +++ b/specs/wv2winrt-cacheable-properties.md @@ -25,8 +25,8 @@ performance. Boolean Available { get; }; // This property has one value for the lifetime of the object so we mark it - // readonly to improve wv2winrt performance. - [corewebview2readonly] + // memoizable to improve runtime performance. + [memoizable] String Model { get; }; // ... @@ -38,16 +38,34 @@ performance. ```c# (but really MIDL3) namespace Microsoft.Web.WebView2.Core { - /// You can use the CoreWebView2ReadOnly attribute on a runtimeclass property - /// definition in MIDL3 if the property value doesn't change for the lifetime - /// of its object. When an object is projected into JavaScript via + /// You can use the `memoizable` attribute on a runtimeclass property + /// or runtimeclass method to indicate that the property value or + /// method return value can be cached. + /// + /// You can apply it to an instance property if the property + /// value doesn't change for the lifetime of its object instance. + /// You can apply it to a static property if the property value + /// doesn't change for the lifetime of the process. + /// You can apply it to an instance method if when the method is called + /// with the same parameters it always returns the same value for the + /// lifetime of its object instance. + /// You can apply it to a static method if when the method is called + /// with the same parameters it always returns the same value for the + /// lifetime of the process. + /// If the property type or the method return type is an object, the property + /// value must be the same object by reference or the method must return the + /// same object by reference in order to be memoizable. Merely returning an + /// equivalent but different object is not sufficient to be memoizable. + /// Similarly, a method call having the same parameters means the same object + /// references and not equivalent but different objects. + /// + /// When an object is projected into JavaScript via /// `CoreWebView2.AddHostObjectToScript`, WebView2 will cache property values /// marked with this attribute. This can potentially improve performance by - /// reducing the number of cross-process calls to obtain the latest value of - /// the property. - [attributeusage(target_property)] - [attributename("corewebview2readonly")] - attribute CoreWebView2ReadOnlyAttribute + /// reducing the number of cross-process calls to obtain the latest value. + [attributeusage(target_property, target_method)] + [attributename("memoizable")] + attribute MemoizableAttribute { } } @@ -56,14 +74,14 @@ namespace Microsoft.Web.WebView2.Core # Appendix Names considered for the attribute: - * **Cacheable**: Caching is what WebView2 will do with the property rather than describing - an aspect of the runtimeclass property. + * **Cacheable** * **ReadOnly**: Similar to C#'s readonly keyword which indicates a value won't change (once - initialized). A more familiar term to end developers than 'immutable'. It does - convey that the caller can't set it, but does it also convey that the implementer also - cannot change the value? - * **Immutable**: Perhaps more explicit than readonly that the implementer also cannot - change the value, but perhaps less familiar of a term. + initialized). But does not convey that the implementer cannot change the value. + * **Immutable**: Similar to readonly + * **Const**: Does a better job indicating that the value does not change even by the + implementer. + * **Memoizable**: A broader term than cacheable that also applies to methods but more specific + than cacheable in that it better defines the kind of caching. For the sample code, the only code you have to write is applying the attribute to the property. The only effect this has is to potentially improve performance so there's no other From 843db4b6853878b1c4f54d6694c22f1789650f1a Mon Sep 17 00:00:00 2001 From: David Risney Date: Tue, 8 Nov 2022 16:08:52 -0800 Subject: [PATCH 3/3] Change to cacheable --- specs/wv2winrt-cacheable-properties.md | 18 ++++++------------ 1 file changed, 6 insertions(+), 12 deletions(-) diff --git a/specs/wv2winrt-cacheable-properties.md b/specs/wv2winrt-cacheable-properties.md index 94170e9f9..23c015b40 100644 --- a/specs/wv2winrt-cacheable-properties.md +++ b/specs/wv2winrt-cacheable-properties.md @@ -25,8 +25,8 @@ performance. Boolean Available { get; }; // This property has one value for the lifetime of the object so we mark it - // memoizable to improve runtime performance. - [memoizable] + // cacheable to improve runtime performance. + [cacheable] String Model { get; }; // ... @@ -38,7 +38,7 @@ performance. ```c# (but really MIDL3) namespace Microsoft.Web.WebView2.Core { - /// You can use the `memoizable` attribute on a runtimeclass property + /// You can use the `cacheable` attribute on a runtimeclass property /// or runtimeclass method to indicate that the property value or /// method return value can be cached. /// @@ -52,20 +52,14 @@ namespace Microsoft.Web.WebView2.Core /// You can apply it to a static method if when the method is called /// with the same parameters it always returns the same value for the /// lifetime of the process. - /// If the property type or the method return type is an object, the property - /// value must be the same object by reference or the method must return the - /// same object by reference in order to be memoizable. Merely returning an - /// equivalent but different object is not sufficient to be memoizable. - /// Similarly, a method call having the same parameters means the same object - /// references and not equivalent but different objects. /// /// When an object is projected into JavaScript via /// `CoreWebView2.AddHostObjectToScript`, WebView2 will cache property values /// marked with this attribute. This can potentially improve performance by /// reducing the number of cross-process calls to obtain the latest value. [attributeusage(target_property, target_method)] - [attributename("memoizable")] - attribute MemoizableAttribute + [attributename("cacheable")] + attribute CacheableAttribute { } } @@ -74,7 +68,7 @@ namespace Microsoft.Web.WebView2.Core # Appendix Names considered for the attribute: - * **Cacheable** + * **Cacheable**: A familiar term also used by python that more closely matches this feature. * **ReadOnly**: Similar to C#'s readonly keyword which indicates a value won't change (once initialized). But does not convey that the implementer cannot change the value. * **Immutable**: Similar to readonly