Add object lifetime and reference tracking documentation#2460
Open
Sergio0694 wants to merge 2 commits into
Open
Add object lifetime and reference tracking documentation#2460Sergio0694 wants to merge 2 commits into
Sergio0694 wants to merge 2 commits into
Conversation
Add a guide describing how C#/WinRT 3.0 manages the lifetime of projected Windows Runtime objects across the .NET garbage collector, COM reference counting, and the XAML reference tracker. It covers RCWs (projected types deriving from WindowsRuntimeObject, with native objects owned by free-threaded and context-aware WindowsRuntimeObjectReference instances), CCWs created through WindowsRuntimeComWrappers, COM aggregation for types extending unsealed Windows Runtime types, tear-off interface handling, and IReferenceTracker integration for XAML, including native/managed reference-cycle collection. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Add the new object lifetime and reference tracking guide to the documentation list in the repository README, following the existing docs cross-reference convention. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Closed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Add a documentation guide describing how CsWinRT 3.0 manages the lifetime of projected Windows Runtime objects across the three systems involved: the .NET garbage collector, COM reference counting, and the XAML reference tracker.
Motivation
CsWinRT bridges three independent lifetime-management systems, and getting their interaction right is subtle (COM aggregation, tear-off interfaces, and reference-tracker cycles in particular). There was previously no conceptual reference for this in the 3.0 docs. This guide gives contributors an accurate mental model of how RCWs, CCWs, and reference tracking work, grounded in the current
WinRT.Runtime2implementation.The content is adapted from the never-merged memory management doc (PR #899), which targeted CsWinRT 2.x and had accumulated unresolved review feedback. It has been rewritten to match the actual CsWinRT 3.0 runtime and to incorporate that feedback.
Changes
docs/memory-management.md: new guide covering COM reference counting for RCWs (projected types deriving fromWindowsRuntimeObject, with native objects owned by free-threaded and context-awareWindowsRuntimeObjectReferenceinstances, plus GC memory pressure and agility), CCWs created throughWindowsRuntimeComWrappers, COM aggregation for managed types extending unsealed Windows Runtime types, tear-off interface handling, andIReferenceTrackerintegration for XAML (including native/managed reference-cycle collection).README.md: link the new guide from the "Getting started" documentation list.Notes
WinRT.Runtime2sources (theWindowsRuntimeObjectReferencehierarchy,WindowsRuntimeObject,WindowsRuntimeComWrappers, and the object marshallers).