Skip to content

Commit a4388bf

Browse files
Apply suggestions from code review
Feedback Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com>
1 parent ee0daf6 commit a4388bf

File tree

1 file changed

+13
-11
lines changed

1 file changed

+13
-11
lines changed

xml/System.Runtime.InteropServices/ComWrappers.xml

Lines changed: 13 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -34,23 +34,25 @@ The <xref:System.Runtime.InteropServices.ComWrappers> API provides support for t
3434
3535
Traditionally in the runtime, a native proxy to managed object is called a COM Callable Wrapper (CCW), and a managed proxy to a native object is called a Runtime Callable Wrapper (RCW). However, when used here, those terms should not be confused with the built-in features of the same name (that is, [CCW](https://docs.microsoft.com/dotnet/standard/native-interop/com-callable-wrapper) and [RCW](https://docs.microsoft.com/dotnet/standard/native-interop/runtime-callable-wrapper)). Unlike the built-in features, a majority of the responsibility for accurate lifetime management, dispatching methods, and marshalling of arguments and return values is left to the `ComWrappers` implementer.
3636
37-
Minimal support is defined by the following features:
38-
1. Efficient mapping between a managed object and a native proxy (e.g. CCW).
39-
2. Efficient mapping between a native `IUnknown` and its managed proxy (e.g. RCW).
40-
3. Integration with the Garbage Collector through the [`IReferenceTrackerHost`](https://docs.microsoft.com/windows/win32/api/windows.ui.xaml.hosting.referencetracker/nn-windows-ui-xaml-hosting-referencetracker-ireferencetrackerhost) interface contract.
41-
- Leveraging this is a very advanced scenario.
37+
"Minimal support" is defined by the following features:
38+
39+
1. Efficient mapping between a managed object and a native proxy (for example, CCW).
40+
2. Efficient mapping between a native `IUnknown` and its managed proxy (for example, RCW).
41+
3. Integration with the garbage collector through the <xref:NN:windows.ui.xaml.hosting.referencetracker.IReferenceTrackerHost> interface contract.
42+
43+
Leveraging this is an advanced scenario.
4244
4345
### Proxy state
4446
45-
Provided below are descriptions and illustrations of proxy state after their respective creation.
47+
This section provides descriptions and illustrations of native and managed proxy state after their respective creation.
4648
47-
In the below illustrations, a strong reference is depicted as a solid line (i.e. `===`) and a weak reference is depicted as a dashed line (i.e. `= = =`). The terms "strong" and "weak" reference should be interpreted as "extending lifetime" and "not extending lifetime" as opposed to implying a specific implementation.
49+
In the following illustrations, a strong reference is depicted as a solid line (`===`) and a weak reference is depicted as a dashed line (`= = =`). The terms "strong reference" and "weak reference" should be interpreted as "extending lifetime" and "not extending lifetime", as opposed to implying a specific implementation.
4850
49-
The state of the managed object and native proxy after a call to [`ComWrappers.GetOrCreateComInterfaceForObject`](https://docs.microsoft.com/dotnet/api/system.runtime.interopservices.comwrappers.getorcreatecominterfaceforobject) is illustrated below.
51+
The following illustration shows the state of the managed object and native proxy after a call to <xref:System.Runtime.InteropServices.ComWrappers.GetOrCreateComInterfaceForObject(System.Object,System.Runtime.InteropServices.CreateComInterfaceFlags)?displayProperty=nameWithType>.
5052
5153
```
5254
-------------------- ----------------------
53-
| Manage object | | Native proxy |
55+
| Managed object | | Native proxy |
5456
| | | Ref count: 1 |
5557
| ---------------- | | ------------------ |
5658
| | Weak reference |=| = = = = = = = >| | Strong reference | |
@@ -59,7 +61,7 @@ The state of the managed object and native proxy after a call to [`ComWrappers.G
5961
-------------------- ----------------------
6062
```
6163
62-
The state of the native object and managed proxy after a call to [`ComWrappers.GetOrCreateObjectForComInstance`](https://docs.microsoft.com/dotnet/api/system.runtime.interopservices.comwrappers.getorcreateobjectforcominstance) is illustrated below. The concept of "identity" follows the [rules for `IUnknown`](https://docs.microsoft.com/windows/win32/com/rules-for-implementing-queryinterface#objects-must-have-identity).
64+
The next illustration shows the state of the native object and managed proxy after a call to <xref:System.Runtime.InteropServices.ComWrappers.GetOrCreateObjectForComInstance(System.IntPtr,System.Runtime.InteropServices.CreateObjectFlags)?displayProperty=nameWithType>. The concept of "identity" follows the [rules for `IUnknown`](https://docs.microsoft.com/windows/win32/com/rules-for-implementing-queryinterface#objects-must-have-identity).
6365
6466
```
6567
------------------ ------------------
@@ -74,7 +76,7 @@ The state of the native object and managed proxy after a call to [`ComWrappers.
7476
| native object. |
7577
------------------------
7678
```
77-
Observe in the above illustration only weak references exist from the runtime perspective. The `+1` reference count on the native object is assumed to be performed by the managed proxy creator (i.e. `ComWrappers` implementer) to ensure the associated lifetime between the native object and its managed proxy. There is an optional strong reference (i.e. `AddRef()`) mentioned in the managed proxy, which is used to support scenario (3) above - see [`CreateObjectFlags.TrackerObject`](https://docs.microsoft.com/dotnet/api/system.runtime.interopservices.createobjectflags). With this optional strong reference the reference count would be `+2`.
79+
Observe that only weak references exist from the runtime perspective. The `+1` reference count on the native object is assumed to be performed by the managed proxy creator (that is, the `ComWrappers` implementer) to ensure the associated lifetime between the native object and its managed proxy. There is an optional strong reference (that is, `AddRef()`) mentioned in the managed proxy, which is used to support scenario (3) mentioned earlier. See <xref:System.Runtime.InteropServices.CreateObjectFlags.TrackerObject?displayProperty=nameWithType>. With this optional strong reference, the reference count would be `+2`.
7880
7981
]]></format>
8082
</remarks>

0 commit comments

Comments
 (0)