GC.AddMemoryPressure(Int64) Method
Definition
Important
Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
Informs the runtime of a large allocation of unmanaged memory that should be taken into account when scheduling garbage collection.
public:
static void AddMemoryPressure(long bytesAllocated);[System.Security.SecurityCritical]
public static void AddMemoryPressure(long bytesAllocated);public static void AddMemoryPressure(long bytesAllocated);[<System.Security.SecurityCritical>]
static member AddMemoryPressure : int64 -> unitstatic member AddMemoryPressure : int64 -> unitPublic Shared Sub AddMemoryPressure (bytesAllocated As Long)Parameters
- bytesAllocated
- Int64
The incremental amount of unmanaged memory that has been allocated.
- Attributes
Exceptions
bytesAllocated is less than or equal to 0.
-or-
On a 32-bit computer, bytesAllocated is larger than Int32.MaxValue.
Remarks
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 AddMemoryPressure and RemoveMemoryPressure 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.
The AddMemoryPressure and RemoveMemoryPressure 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.
In the simplest usage pattern, a managed object allocates unmanaged memory in the constructor and releases it in the Finalize method. Call the AddMemoryPressure method after allocating the unmanaged memory, and call the RemoveMemoryPressure 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 AddMemoryPressure and RemoveMemoryPressure methods to communicate these incremental changes to the runtime.
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.
