From 3441ec1af70db0958c9e9d4f4b1d7884aa493d4f Mon Sep 17 00:00:00 2001 From: Maoni0 Date: Wed, 8 Jan 2025 20:51:16 -0800 Subject: [PATCH 1/2] amp_rmp --- xml/System/GC.xml | 16 ++++------------ 1 file changed, 4 insertions(+), 12 deletions(-) diff --git a/xml/System/GC.xml b/xml/System/GC.xml index a20a3afbba8..f28d29d4a61 100644 --- a/xml/System/GC.xml +++ b/xml/System/GC.xml @@ -126,13 +126,9 @@ The following example uses several GC methods to get generation and memory infor method informs the runtime of this additional pressure on system memory. + The common pattern of releasing native resources is via a finalizer on the type. If a managed object uses native memory, it could free that native memory in its finalizer. The garbage collector only knows about managed memory and schedules collections based on this knowledge. Imagine a scenario where a small managed object is associated with a large amount of native memory usage and this managed object now lives in gen2. A gen2 GC may not happen for quite some time which means this large amount of native memory will not be released till the next gen2 happens. The runtime provides the and methods to help with this scenario. The runtime keeps an internal record of how much these APIs added and removed, and triggers a gen2 GC if deemed productive. So this is not a feature of the GC but rather something that the runtime provides to trigger GCs. - The and methods improve performance only for types that exclusively depend on finalizers to release the unmanaged resources. It's not necessary to use these methods in types that follow the dispose pattern, where finalizers are used to clean up unmanaged resources only in the event that a consumer of the type forgets to call `Dispose`. For more information on object finalization and the dispose pattern, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). - - In the simplest usage pattern, a managed object allocates unmanaged memory in the constructor and releases it in the `Finalize` method. Call the method after allocating the unmanaged memory, and call the method after releasing it. - - In more complicated scenarios, where the unmanaged memory allocation changes substantially during the lifetime of the managed object, you can call the and methods to communicate these incremental changes to the runtime. + If you have a convenient place to call these APIs, you don't necessarily have to have a finalizer. For example, when a specific method on the type is called you know you can release the native memory, you can call the method at that point instead of having a finalizer. > [!CAUTION] > You must ensure that you remove exactly the amount of pressure you add. Failing to do so can adversely affect the performance of the system in applications that run for long periods of time. @@ -1701,13 +1697,9 @@ The following example demonstrates the use of the method informs the runtime of this additional pressure on system memory, and the method informs the runtime that the additional pressure has been released. - - The and methods improve performance only for types that exclusively depend on finalizers to release the unmanaged resources. It's not necessary to use these methods in types that follow the dispose pattern, where finalizers are used to clean up unmanaged resources only in the event that a consumer of the type forgets to call `Dispose`. For more information on object finalization and the dispose pattern, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). - - In the simplest usage pattern, a managed object allocates unmanaged memory in the constructor and releases it in the `Finalize` method. Call the method after allocating the unmanaged memory, and call the method after releasing it. + The common pattern of releasing native resources is via a finalizer on the type. If a managed object uses native memory, it could free that native memory in its finalizer. The garbage collector only knows about managed memory and schedules collections based on this knowledge. Imagine a scenario where a small managed object is associated with a large amount of native memory usage and this managed object now lives in gen2. A gen2 GC may not happen for quite some time which means this large amount of native memory will not be released till the next gen2 happens. The runtime provides the and methods to help with this scenario. The runtime keeps an internal record of how much these APIs added and removed, and triggers a gen2 GC if deemed productive. So this is not a feature of the GC but rather something that the runtime provides to trigger GCs. - In more complicated scenarios, where the unmanaged memory allocation changes substantially during the lifetime of the managed object, you can call the and methods to communicate these incremental changes to the runtime. + If you have a convenient place to call these APIs, you don't necessarily have to have a finalizer. For example, when a specific method on the type is called you know you can release the native memory, you can call the method at that point instead of having a finalizer. > [!CAUTION] > You must ensure that you remove exactly the amount of pressure you add. Failing to do so can adversely affect the performance of the system in applications that run for long periods of time. From 78dc5f049fb7e913f2659857ba48fbdd75d3de9c Mon Sep 17 00:00:00 2001 From: Maoni0 Date: Thu, 9 Jan 2025 11:40:09 -0800 Subject: [PATCH 2/2] CR feedback --- xml/System/GC.xml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/xml/System/GC.xml b/xml/System/GC.xml index f28d29d4a61..2e66ec4d671 100644 --- a/xml/System/GC.xml +++ b/xml/System/GC.xml @@ -126,9 +126,9 @@ The following example uses several GC methods to get generation and memory infor and methods to help with this scenario. The runtime keeps an internal record of how much these APIs added and removed, and triggers a gen2 GC if deemed productive. So this is not a feature of the GC but rather something that the runtime provides to trigger GCs. + The common pattern for releasing native resources is via a type's finalizer. If a managed object uses native memory, it can free that native memory in its finalizer. The garbage collector only knows about managed memory and schedules collections based on this knowledge. Imagine a scenario where a small managed object is associated with a large amount of native memory usage, and this managed object now lives in gen2. A gen2 GC might not happen for some time, which means the large amount of native memory won't be released until the next gen2 happens. The runtime provides the and methods to help with this scenario. The runtime keeps an internal record of how much memory pressure these APIs added and removed, and triggers a gen2 GC if deemed productive. So this is not a feature of the GC but rather something that the runtime provides to trigger GCs. - If you have a convenient place to call these APIs, you don't necessarily have to have a finalizer. For example, when a specific method on the type is called you know you can release the native memory, you can call the method at that point instead of having a finalizer. + If you have a convenient place to call these APIs, you don't necessarily have to use a finalizer. For example, if you know you can release the native memory when a specific method on the type is called, you can call the method at that point instead of having a finalizer. > [!CAUTION] > You must ensure that you remove exactly the amount of pressure you add. Failing to do so can adversely affect the performance of the system in applications that run for long periods of time. @@ -1697,9 +1697,9 @@ The following example demonstrates the use of the and methods to help with this scenario. The runtime keeps an internal record of how much these APIs added and removed, and triggers a gen2 GC if deemed productive. So this is not a feature of the GC but rather something that the runtime provides to trigger GCs. + The common pattern for releasing native resources is via a type's finalizer. If a managed object uses native memory, it can free that native memory in its finalizer. The garbage collector only knows about managed memory and schedules collections based on this knowledge. Imagine a scenario where a small managed object is associated with a large amount of native memory usage, and this managed object now lives in gen2. A gen2 GC might not happen for some time, which means the large amount of native memory won't be released until the next gen2 happens. The runtime provides the and methods to help with this scenario. The runtime keeps an internal record of how much memory pressure these APIs added and removed, and triggers a gen2 GC if deemed productive. So this is not a feature of the GC but rather something that the runtime provides to trigger GCs. - If you have a convenient place to call these APIs, you don't necessarily have to have a finalizer. For example, when a specific method on the type is called you know you can release the native memory, you can call the method at that point instead of having a finalizer. + If you have a convenient place to call these APIs, you don't necessarily have to use a finalizer. For example, if you know you can release the native memory when a specific method on the type is called, you can call the method at that point instead of having a finalizer. > [!CAUTION] > You must ensure that you remove exactly the amount of pressure you add. Failing to do so can adversely affect the performance of the system in applications that run for long periods of time.