Memory management doc by manodasanW · Pull Request #899 · microsoft/CsWinRT

manodasanW · 2021-06-29T18:45:37Z

Documenting what we learned when working on the fix for the memory management issues in C#/WinRT.

Fixes #810

AaronRobinsonMSFT

AaronRobinsonMSFT · 2021-06-29T19:48:56Z

docs/memorymanagement.md

+
+In the former, the object is implemented purely in C# and its lifetime is managed by the .NET
+garbage collector. C#/WinRT only comes into play when this C# object is passed across the ABI to a
+WinRT function. When this happens, C#/WinRT creates a CCW for it using the .NET 5 ComWrappers API


Link to the ComWrappers API? https://docs.microsoft.com/dotnet/api/system.runtime.interopservices.comwrappers

docs/memorymanagement.md

AaronRobinsonMSFT · 2021-06-29T19:56:45Z

docs/memorymanagement.md

+know about all the references to it from another reference tracking system like the .NET
+garbage collector. This allows XAML to track scenarios where objects may have circular references
+or only have references to it from objects that are pending clean up. Specifically, when a C# wrapper
+is created for a XAML runtime tracked object (implements `IReferenceTracker`), the XAML runtime


Link to API? https://docs.microsoft.com/windows/win32/api/windows.ui.xaml.hosting.referencetracker/

docs/memorymanagement.md

AaronRobinsonMSFT · 2021-06-29T19:59:39Z

docs/memorymanagement.md

+serves the purpose of documenting how C#/WinRT interacts with all 3 systems to correctly manage the
+lifetime of projected WinRT objects.
+
+### COM reference tracking


It might be easier to augment this with a series of enumerated steps in the process.

Co-authored-by: Aaron Robinson <arobins@microsoft.com>

angelazhangmsft · 2021-07-08T22:55:03Z

docs/memorymanagement.md

+which C#/WinRT does behind the scenes when a C# class extends such a projected type. In COM aggregation,
+there is 2 objects in play: the outer object which is the CCW for the C# object and the inner object
+which is the WinRT object being extended. Both these objects are made to look like one object known as the
+


Unexpected line break? Also some line breaks below this when viewing the preview non-markdown version of the doc

angelazhangmsft · 2021-07-08T22:58:59Z

docs/memorymanagement.md

+
+The above describes what typically happens for any natively implemented WinRT object that C#/WinRT
+projects. There are some differences to this when the object is instead a C# implemented object that is
+projected into WinRT via a COM callable wrapper (CCW). This is done via a C# class implementing a set of


Maybe factor out these into 2 separate sections? E.g.

C# class implementing WinRT interface
...
C# class extending an unsealed WinRT type
...

Scottj1s · 2021-07-21T21:53:06Z

docs/memorymanagement.md

+
+### COM reference tracking
+
+Each WinRT object that we project is based on COM and implements a set of interfaces.


we -> C#/WinRT

Scottj1s · 2021-07-21T21:56:03Z

docs/memorymanagement.md

+
+Each WinRT object that we project is based on COM and implements a set of interfaces.
+As per the COM design, every COM interface implements `IUnknown` which has an `AddRef` and `Release`
+function. C#/WinRT calls the `AddRef` function anytime it gets a new reference to a WinRT object


You mention CCWs below. Maybe introduce IObjectReference as the RCW here.

Scottj1s · 2021-07-21T21:58:20Z

docs/memorymanagement.md

+As per the COM design, every COM interface implements `IUnknown` which has an `AddRef` and `Release`
+function. C#/WinRT calls the `AddRef` function anytime it gets a new reference to a WinRT object
+which C#/WinRT holds onto using an `IObjectReference` instance. It also calls `AddRef` whenever it gives
+out a reference to one of these objects across the ABI as an out parameter. C#/WinRT calls the


should introduce this acronym too: Application Binary Interface (ABI)

Scottj1s · 2021-07-21T22:00:20Z

docs/memorymanagement.md

+object alive and that is managed by the .NET runtime and `ComWrappers` implementation.
+
+
+In the latter scenario, extending an unsealed WinRT type is typically done via COM Aggregation


"latter" here is referring back a bit - may help to provide some structure to the doc (section titles)

Scottj1s · 2021-07-21T22:00:41Z

docs/memorymanagement.md

+
+In the latter scenario, extending an unsealed WinRT type is typically done via COM Aggregation
+which C#/WinRT does behind the scenes when a C# class extends such a projected type. In COM aggregation,
+there is 2 objects in play: the outer object which is the CCW for the C# object and the inner object


there are two

Scottj1s · 2021-07-21T22:01:37Z

docs/memorymanagement.md

+composed object. To achieve that, the outer object delegates calls for any of the inner object
+
+interfaces that aren't overridden to the inner object. Any calls for interfaces that are only
+implemented on the outer object or is overridden by the outer object or is for the `IUnknown` interface


or are overridden ..., or are for ....

Scottj1s · 2021-07-21T22:02:49Z

docs/memorymanagement.md

+
+
+In the latter scenario, extending an unsealed WinRT type is typically done via COM Aggregation
+which C#/WinRT does behind the scenes when a C# class extends such a projected type. In COM aggregation,


I'd include links inline in the body of the text, rather than at the end of the doc, like COM Aggregation here (https://docs.microsoft.com/en-us/windows/win32/com/aggregation)

Scottj1s · 2021-07-21T22:04:29Z

docs/memorymanagement.md

+would be handled by the outer object itself. The last part means that the lifetime and the COM reference
+counting of this aggregated object is maintained by the outer object and more specifically its `IUnknown`
+implementation on the CCW from ComWrappers. This is where the standard COM reference tracking
+convention described earlier starts to differ. As we know for CCWs, there are 2 things which


spell out any number less than 10 (standard technical writing guideline)

Scottj1s · 2021-07-21T22:07:09Z

docs/memorymanagement.md

+other than facilitating QI calls for them from the native side where `Release` isn't called right after.
+The recommendation for tear off interfaces which do want to support such uses on aggregated objects
+is that they can continue to be constructed on demand upon the first QI for it, but the interface
+should not be cleaned up until the object is cleaned up even if there are no longer any reference


can we be more crisp about the recommendation - that a tear-off implementor should cache all instances to prevent premature destruction?

Scottj1s · 2021-07-21T22:08:59Z

docs/memorymanagement.md

+objects if one of these interfaces need to be QIed for by the composed object as part of the
+projection implementation. This is because a `Release` would happen right after which would trigger
+the cleanup of the interface as its lifetime isn't tied to the outer. Given that tear off interfaces
+are rare and not typically used by C# consumers, C#/WinRT today doesn't address this


"not typically used by C# consumers" ? the tear-off implementor has no idea what client code is using it

Scottj1s · 2021-07-21T22:13:42Z

docs/memorymanagement.md

+or only have references to it from objects that are pending clean up. Specifically, when a C# wrapper
+is created for a XAML runtime tracked object (implements `IReferenceTracker`), the XAML runtime
+needs to be informed of it by a call to `ConnectFromTrackerSource` on `IReferenceTracker`. This is
+done by the ComWrappers implementation when an RCW is created. After that, any references to that


(introduce 'RCW' above)

Scottj1s · 2021-07-21T22:14:05Z

docs/memorymanagement.md

+needs to be informed of it by a call to `ConnectFromTrackerSource` on `IReferenceTracker`. This is
+done by the ComWrappers implementation when an RCW is created. After that, any references to that
+object that are tracked by the other reference tracking system (.NET garbage collector in this case)
+needs to be informed to XAML by a call to `AddRefFromTrackerSource`. This is done by both C#/WinRT and


Scottj1s · 2021-07-21T22:17:23Z

docs/memorymanagement.md

+needs to be informed to XAML by a call to `AddRefFromTrackerSource`. This is done by both C#/WinRT and
+ComWrappers after any `AddRef` call to increment the COM reference count. Similarly, before the
+`Release` call, there would be a `ReleaseFromTrackerSource` to indicate a reference on the object
+was released. When the RCW is destructed, there would similarly be a call to


destructed -> finalized

manodasanW added 3 commits June 29, 2021 10:54

Add memory management doc

a5826fa

Fixes

9152a3b

Fix links.

6039e5c

manodasanW requested review from AaronRobinsonMSFT, MikeHillberg, Scottj1s and angelazhangmsft June 29, 2021 18:45

AaronRobinsonMSFT reviewed Jun 29, 2021

View reviewed changes

Apply suggestions from code review

13a203f

Co-authored-by: Aaron Robinson <arobins@microsoft.com>

angelazhangmsft reviewed Jul 8, 2021

View reviewed changes

Scottj1s reviewed Jul 21, 2021

View reviewed changes


		### COM reference tracking

		Each WinRT object that we project is based on COM and implements a set of interfaces.

		object alive and that is managed by the .NET runtime and `ComWrappers` implementation.


		In the latter scenario, extending an unsealed WinRT type is typically done via COM Aggregation



		In the latter scenario, extending an unsealed WinRT type is typically done via COM Aggregation
		which C#/WinRT does behind the scenes when a C# class extends such a projected type. In COM aggregation,

Conversation

manodasanW commented Jun 29, 2021

Uh oh!

AaronRobinsonMSFT left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Scottj1s Jul 21, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Scottj1s Jul 21, 2021 •

edited

Loading