Skip to content

Add object lifetime and reference tracking documentation#2460

Open
Sergio0694 wants to merge 2 commits into
staging/3.0from
user/sergiopedri/memory-management-doc
Open

Add object lifetime and reference tracking documentation#2460
Sergio0694 wants to merge 2 commits into
staging/3.0from
user/sergiopedri/memory-management-doc

Conversation

@Sergio0694

Copy link
Copy Markdown
Member

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.Runtime2 implementation.

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 from WindowsRuntimeObject, with native objects owned by free-threaded and context-aware WindowsRuntimeObjectReference instances, plus GC memory pressure and agility), CCWs created through WindowsRuntimeComWrappers, COM aggregation for managed types extending unsealed Windows Runtime types, tear-off interface handling, and IReferenceTracker integration for XAML (including native/managed reference-cycle collection).
  • README.md: link the new guide from the "Getting started" documentation list.

Notes

  • All descriptions were verified against the WinRT.Runtime2 sources (the WindowsRuntimeObjectReference hierarchy, WindowsRuntimeObject, WindowsRuntimeComWrappers, and the object marshallers).
  • The review comments left on PR Memory management doc #899 were revisited; the valid ones (API links, acronym introductions, sectioning, the tear-off recommendation, and grammar/style) are addressed in this rewrite.

Sergio0694 and others added 2 commits June 19, 2026 13:47
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>
@Sergio0694 Sergio0694 added documentation Improvements or additions to documentation CsWinRT 3.0 labels Jun 19, 2026
@Sergio0694 Sergio0694 requested a review from manodasanW June 19, 2026 21:03
@Sergio0694 Sergio0694 mentioned this pull request Jun 19, 2026
@Sergio0694 Sergio0694 linked an issue Jun 19, 2026 that may be closed by this pull request
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

CsWinRT 3.0 documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Documentation for C#/WinRT memory management

1 participant