GC.TryStartNoGCRegion Method (Int64)

.NET Framework (current version)
 
System_CAPS_noteNote

The .NET API Reference documentation has a new home. Visit the .NET API Browser on docs.microsoft.com to see the new experience.

Attempts to disallow garbage collection during the execution of a critical path if a specified amount of memory is available.

Namespace:   System
Assembly:  mscorlib (in mscorlib.dll)

[SecurityCriticalAttribute]
public static bool TryStartNoGCRegion(
	long totalSize
)

Parameters

totalSize
Type: System.Int64

The amount of memory in bytes to allocate without triggering a garbage collection. It must be less than or equal to the size of an ephemeral segment. For information on the size of an ephemeral segement, see the "Ephemeral generations and segments" section in the Fundamentals of Garbage Collection article.

Return Value

Type: System.Boolean

true if the runtime was able to commit the required amount of memory and the garbage collector is able to enter no GC region latency mode; otherwise, false.

Exception Condition
ArgumentOutOfRangeException

totalSize exceeds the ephemeral segment size.

InvalidOperationException

The process is already in no GC region latency mode.

The TryStartNoGCRegion(Int64) method attempts to place the garbage collector in no GC region latency mode, which disallows garbage collection while an app executes a critical region of code. If the runtime is unable to initially allocate the requested amount of memory, the garbage collector performs a full blocking garbage collection in an attempt to free additional memory. The garbage collector enters no GC region latency mode if it is able to allocate the required amount of memory, which in this case is actually 2 * totalSize bytes (it attempts to allocate totalSize bytes for the small object heap and totalSize bytes for the large object heap).

totalSize must be large enough to handle all memory allocations that occur in the critical path. This includes allocations by the app, as well as allocations that the runtime makes on the app's behalf.

System_CAPS_importantImportant

You cannot nest calls to the TryStartNoGCRegion method, and you should only call the EndNoGCRegion method if the runtime is currently in no GC region latency mode. In other words, you should not call TryStartNoGCRegion multiple times (after the first method call, subsequent calls will not succeed), and you should not expect calls to EndNoGCRegion to succeed just because the first call to TryStartNoGCRegion succeeded.

You exit the no GC region latency mode by calling the EndNoGCRegion method.

.NET Framework
Available since 4.6
Return to top
Show: