.NET Framework Class Library
GC..::.RegisterForFullGCNotification Method

[This documentation is for preview only, and is subject to change in later releases. Blank topics are included as placeholders.]

Specifies that a garbage collection notification should be raised when conditions favor full garbage collection and when the collection has been completed.

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

Visual Basic (Declaration)
Public Shared Sub RegisterForFullGCNotification ( _
    maxGenerationThreshold As Integer, _
    largeObjectHeapThreshold As Integer _
)
Visual Basic (Usage)
Dim maxGenerationThreshold As Integer
Dim largeObjectHeapThreshold As Integer

GC.RegisterForFullGCNotification(maxGenerationThreshold, _
    largeObjectHeapThreshold)
C#
public static void RegisterForFullGCNotification(
    int maxGenerationThreshold,
    int largeObjectHeapThreshold
)
Visual C++
public:
static void RegisterForFullGCNotification(
    int maxGenerationThreshold, 
    int largeObjectHeapThreshold
)
F#
static member RegisterForFullGCNotification : 
        maxGenerationThreshold:int * 
        largeObjectHeapThreshold:int -> unit 

Parameters

maxGenerationThreshold
Type: System..::.Int32
A number between 1 and 99 that specifies when the notification should be raised based on the objects surviving in generation 2.
largeObjectHeapThreshold
Type: System..::.Int32
A number between 1 and 99 that specifies when the notification should be raised based on objects allocated in the large object heap.
Exceptions

ExceptionCondition
InvalidOperationException

This member is not available when concurrent garbage collection is enabled. See the <gcConcurrent> runtime setting for information about how to disable concurrent garbage collection.

ArgumentOutOfRangeException

maxGenerationThreshold or largeObjectHeapThreshold is not between 1 and 99.

Remarks

If you have situations in which a full garbage collection by the common language runtime would adversely affect your application's performance, you can determine whether the runtime is about to induce a full garbage collection and circumvent that collection by inducing a collection yourself (using the Collect method) when conditions are still favorable. For more information about what represents a full garbage collection, see Garbage Collection Notifications.

When you register for a garbage collection notification, you can determine whether the event that signals an approaching full garbage collection has been raised by checking the status of the garbage collection notification. This pattern resembles how the operating system monitors for low memory notifications.

Use the following guidelines for specifying the maxGenerationThreshold and largeObjectHeapThreshold parameters:

  • The larger the threshold value, the further away in time the collection will likely occur and the sooner the notification will be raised.

    A larger threshold value provides more opportunities for the runtime to check for an approaching collection. This increases the likelihood that you will be notified. However, you should not set the threshold too high because that results in a longer wait before the runtime induces the next collection.

    When you induce a collection yourself upon notification using a high threshold value, more objects are reclaimed than would be reclaimed by the runtime's next collection.

  • The smaller the threshold value, the greater the likelihood that a collection will occur sooner and the notification will be raised later.

Examples

The following example shows how to register a garbage collection notification and start a thread to monitor the status of the garbage collection notification. This code example is part of a larger example provided for Garbage Collection Notifications topic.

Visual Basic

    ' Variables for continual checking in the
    ' While loop in the WaitForFullGcProc method.
    Private Shared checkForNotify As Boolean = False

    ' Variable for suspending work 
    ' (such as servicing allocated server requests)
    ' after a notification is received and then 
    ' resuming allocation after inducing a garbage collection.
    Private Shared bAllocate As Boolean = False

    ' Variable for ending the example.
    Private Shared finalExit As Boolean = False

    ' Collection for objects that  
    ' simulate the server request workload.
    Private Shared load As New List(Of Byte())


    Public Shared Sub Main(ByVal args() As String)
        Try
            ' Register for a notification. 
            GC.RegisterForFullGCNotification(10, 10)
            Console.WriteLine("Registered for GC notification.")

            bAllocate = True
            checkForNotify = True

            ' Start a thread using WaitForFullGCProc.
            Dim thWaitForFullGC As Thread = _
                New Thread(New ThreadStart(AddressOf WaitForFullGCProc))
            thWaitForFullGC.Start()

            ' While the thread is checking for notifications in
            ' WaitForFullGCProc, create objects to simulate a server workload.
            Try
                Dim lastCollCount As Integer = 0
                Dim newCollCount As Integer = 0


                While (True)
                    If bAllocate = True Then

                        load.Add(New Byte(1000) {})
                        newCollCount = GC.CollectionCount(2)
                        If (newCollCount <> lastCollCount) Then
                            ' Show collection count when it increases:
                            Console.WriteLine("Gen 2 collection count: {0}", _
                                              GC.CollectionCount(2).ToString)
                            lastCollCount = newCollCount
                        End If

                        ' For ending the example (arbitrary).
                        If newCollCount = 500 Then
                            finalExit = True
                            checkForNotify = False
                            bAllocate = False
                            Exit While
                        End If

                    End If
                End While

            Catch outofMem As OutOfMemoryException
                Console.WriteLine("Out of memory.")
            End Try

            finalExit = True
            checkForNotify = False
            GC.CancelFullGCNotification()

        Catch invalidOp As InvalidOperationException
            Console.WriteLine("GC Notifications are not supported while concurrent GC is enabled." _
                              & vbLf & invalidOp.Message)
        End Try
    End Sub

C#

// Variable for continual checking in the 
// While loop in the WaitForFullGCProc method.
static bool checkForNotify = false;

// Variable for suspending work 
// (such servicing allocated server requests)
// after a notification is received and then 
// resuming allocation after inducing a garbage collection.
static bool bAllocate = false;

// Variable for ending the example.
static bool finalExit = false;

// Collection for objects that  
// simulate the server request workload.
static List<byte[]> load = new List<byte[]>();


public static void Main(string[] args)
{
    try
    {
        // Register for a notification. 
        GC.RegisterForFullGCNotification(10, 10);
        Console.WriteLine("Registered for GC notification.");

        checkForNotify = true;
        bAllocate = true;

        // Start a thread using WaitForFullGCProc.
        Thread thWaitForFullGC = new Thread(new ThreadStart(WaitForFullGCProc));
        thWaitForFullGC.Start();

        // While the thread is checking for notifications in
        // WaitForFullGCProc, create objects to simulate a server workload.
        try
        {

            int lastCollCount = 0;
            int newCollCount = 0;


            while (true)
            {
                if (bAllocate)
                {
                    load.Add(new byte[1000]);
                    newCollCount = GC.CollectionCount(2);
                    if (newCollCount != lastCollCount)
                    {
                        // Show collection count when it increases:
                        Console.WriteLine("Gen 2 collection count: {0}", GC.CollectionCount(2).ToString());
                        lastCollCount = newCollCount;
                    }

                    // For ending the example (arbitrary).
                    if (newCollCount == 500)
                    {
                        finalExit = true;
                        checkForNotify = false;
                        break;
                    }
                }
            }

        }
        catch (OutOfMemoryException)
        {
            Console.WriteLine("Out of memory.");
        }


        finalExit = true;
        checkForNotify = false;
        GC.CancelFullGCNotification();

    }
    catch (InvalidOperationException invalidOp)
    {

        Console.WriteLine("GC Notifications are not supported while concurrent GC is enabled.\n"
            + invalidOp.Message);
    }
}
.NET Framework Security

  • LinkDemand 

    for full trust for the immediate caller. This member cannot be used by partially trusted code.

  • SecurityCriticalAttribute 

    requires full trust for the immediate caller. This member cannot be used by partially trusted or transparent code.

Platforms

Windows 7, Windows Vista, Windows XP SP2, Windows Server 2008, Windows Server 2003

The .NET Framework and .NET Compact Framework do not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.
Version Information

.NET Framework

Supported in: 4, 3.5 SP1, 3.0 SP2, 2.0 SP2

.NET Framework Client Profile

Supported in: 4
See Also

Reference

Other Resources

Page view tracker