Share via


Garbage Collection Notifications

There are situations in which a full garbage collection by the common language runtime may adversely affect performance. This can be an issue particularly with servers that process large volumes of requests; in this case, a long garbage collection can cause a request time-out. To prevent a full collection from occurring during a critical period, you can be notified that a full garbage collection is approaching and then take action to redirect the workload to another server instance. You can also induce a collection yourself, provided that the current server instance does not need to process requests.

Note

This feature is available only when concurrent garbage collection is disabled. By default, concurrent garbage collection is enabled unless you are running in a hosted environment and the host changed the configuration for you. Concurrent garbage collection is not available when server garbage collection is used. This feature does not support concurrent garbage collection because memory allocations are allowed while concurrent garbage collection is in progress. See the <gcConcurrent> runtime setting for information about how to disable concurrent garbage collection.

The RegisterForFullGCNotification method registers for a notification to be raised when the runtime senses that a full garbage collection is approaching. There are two parts to this notification: when the full garbage collection is approaching and when the full garbage collection has completed.

To determine when a notification has been raised, use the WaitForFullGCApproach and WaitForFullGCComplete methods. Typically, you use these methods in a while loop to continually obtain a GCNotificationStatus enumeration that shows the status of the notification. If that value is Succeeded, you can do the following:

  • In response to a notification obtained with the WaitForFullGCApproach method, you can redirect the workload and possibly induce a collection yourself.

  • In response to a notification obtained with the WaitForFullGCComplete method, you can make the current server instance available to process requests again. You can also gather information. For example, you can use the CollectionCount method to record the number of collections.

The WaitForFullGCApproach and the WaitForFullGCComplete methods are designed to work together. Using one without the other can produce indeterminate results.

Full Garbage Collection

The runtime causes a full garbage collection when any of the following scenarios are true:

  • Enough memory has been promoted into generation 2 to cause the next generation 2 collection.

  • Enough memory has been promoted into the large object heap to cause the next generation 2 collection.

  • A collection of generation 1 is escalated to a collection of generation 2 due to other factors.

The thresholds you specify in the RegisterForFullGCNotification method apply to the first two scenarios. However, in the first scenario you will not always receive the notification at the time proportional to the threshold values you specify for two reasons:

  • The runtime does not check each small object allocation (for performance reasons).

  • Only generation 1 collections promote memory into generation 2.

The third scenario also contributes to the uncertainty of when you will receive the notification. Although this is not a guarantee, it does prove to be a useful way to mitigate the effects of an inopportune full garbage collection by redirecting the requests during this time or inducing the collection yourself when it can be better accommodated.

Notification Threshold Parameters

The RegisterForFullGCNotification method has two parameters to specify the threshold values of the generation 2 objects and the large object heap. When those values are met, a garbage collection notification should be raised. The following table describes these parameters.

Parameter

Description

maxGenerationThreshold

A number between 1 and 99 that specifies when the notification should be raised based on the objects promoted in generation 2.

largeObjectHeapThreshold

A number between 1 and 99 that specifies when the notification should be raised based on the objects that are allocated in the large object heap.

If you specify a value that is too high, there is a high probability that you will receive a notification, but it could be too long a period to wait before the runtime causes a collection. If you induce a collection yourself, you may reclaim more objects than would be reclaimed if the runtime causes the collection.

If you specify a value that is too low, the runtime may cause the collection before you have had sufficient time to be notified.

Example

Description

In the following example, a group of servers service incoming Web requests. To simulate the workload of processing requests, byte arrays are added to a List<T> collection. Each server registers for a garbage collection notification and then starts a thread on the WaitForFullGCProc user method to continuously monitor the GCNotificationStatus enumeration that is returned by the WaitForFullGCApproach and the WaitForFullGCComplete methods.

The WaitForFullGCApproach and the WaitForFullGCComplete methods call their respective event-handling user methods when a notification is raised:

  • OnFullGCApproachNotify

    This method calls the RedirectRequests user method, which instructs the request queuing server to suspend sending requests to the server. This is simulated by setting the class-level variable bAllocate to false so that no more objects are allocated.

    Next, the FinishExistingRequests user method is called to finish processing the pending server requests. This is simulated by clearing the List<T> collection.

    Finally, a garbage collection is induced because the workload is light.

  • OnFullGCCompleteNotify

    This method calls the user method AcceptRequests to resume accepting requests because the server is no longer susceptible to a full garbage collection. This action is simulated by setting the bAllocate variable to true so that objects can resume being added to the List<T> collection.

The following code contains the Main method of the example.

' 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
// 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);
    }
}
private:
    // 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<array<Byte>^>^ load = gcnew List<array<Byte>^>();


public:
    static void Main()
    {
        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 = gcnew Thread(gcnew 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(gcnew array<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);
        }
    }

The following code contains the WaitForFullGCProc user method, that contains a continuous while loop to check for garbage collection notifications.

Public Shared Sub WaitForFullGCProc()

    While True 
        ' CheckForNotify is set to true and false in Main. 

        While checkForNotify
            ' Check for a notification of an approaching collection. 
            Dim s As GCNotificationStatus = GC.WaitForFullGCApproach
            If (s = GCNotificationStatus.Succeeded) Then
                Console.WriteLine("GC Notifiction raised.")
                OnFullGCApproachNotify()
            ElseIf (s = GCNotificationStatus.Canceled) Then
                Console.WriteLine("GC Notification cancelled.")
                Exit While 
            Else 
                ' This can occur if a timeout period 
                ' is specified for WaitForFullGCApproach(Timeout)  
                ' or WaitForFullGCComplete(Timeout)   
                ' and the time out period has elapsed. 
                Console.WriteLine("GC Notification not applicable.")
                Exit While 
            End If 

            ' Check for a notification of a completed collection.
            s = GC.WaitForFullGCComplete
            If (s = GCNotificationStatus.Succeeded) Then
                Console.WriteLine("GC Notifiction raised.")
                OnFullGCCompleteEndNotify()
            ElseIf (s = GCNotificationStatus.Canceled) Then
                Console.WriteLine("GC Notification cancelled.")
                Exit While 
            Else 
                ' Could be a time out.
                Console.WriteLine("GC Notification not applicable.")
                Exit While 
            End If 

        End While
        Thread.Sleep(500)
        ' FinalExit is set to true right before   
        ' the main thread cancelled notification. 
        If finalExit Then 
            Exit While 
        End If 

    End While 
End Sub
public static void WaitForFullGCProc()
{
    while (true)
    {
        // CheckForNotify is set to true and false in Main. 
        while (checkForNotify)
        {
            // Check for a notification of an approaching collection.
            GCNotificationStatus s = GC.WaitForFullGCApproach();
            if (s == GCNotificationStatus.Succeeded)
            {
                Console.WriteLine("GC Notifiction raised.");
                OnFullGCApproachNotify();
            }
            else if (s == GCNotificationStatus.Canceled)
            {
                Console.WriteLine("GC Notification cancelled.");
                break;
            }
            else
            {
                // This can occur if a timeout period 
                // is specified for WaitForFullGCApproach(Timeout)  
                // or WaitForFullGCComplete(Timeout)   
                // and the time out period has elapsed. 
                Console.WriteLine("GC Notification not applicable.");
                break;
            }

            // Check for a notification of a completed collection.
            s = GC.WaitForFullGCComplete();
            if (s == GCNotificationStatus.Succeeded)
            {
                Console.WriteLine("GC Notifiction raised.");
                OnFullGCCompleteEndNotify();
            }
            else if (s == GCNotificationStatus.Canceled)
            {
                Console.WriteLine("GC Notification cancelled.");
                break;
            }
            else
            {
                // Could be a time out.
                Console.WriteLine("GC Notification not applicable.");
                break;
            }
        }


        Thread.Sleep(500);
        // FinalExit is set to true right before   
        // the main thread cancelled notification. 
        if (finalExit)
        {
            break;
        }
    }

}
public:
    static void WaitForFullGCProc()
    {
        while (true)
        {
            // CheckForNotify is set to true and false in Main. 
            while (checkForNotify)
            {
                // Check for a notification of an approaching collection.
                GCNotificationStatus s = GC::WaitForFullGCApproach();
                if (s == GCNotificationStatus::Succeeded)
                {
                    Console::WriteLine("GC Notifiction raised.");
                    OnFullGCApproachNotify();
                }
                else if (s == GCNotificationStatus::Canceled)
                {
                    Console::WriteLine("GC Notification cancelled.");
                    break;
                }
                else
                {
                    // This can occur if a timeout period 
                    // is specified for WaitForFullGCApproach(Timeout) 
                    // or WaitForFullGCComplete(Timeout) 
                    // and the time out period has elapsed.
                    Console::WriteLine("GC Notification not applicable.");
                    break;
                }

                // Check for a notification of a completed collection.
                s = GC::WaitForFullGCComplete();
                if (s == GCNotificationStatus::Succeeded)
                {
                    Console::WriteLine("GC Notifiction raised.");
                    OnFullGCCompleteEndNotify();
                }
                else if (s == GCNotificationStatus::Canceled)
                {
                    Console::WriteLine("GC Notification cancelled.");
                    break;
                }
                else
                {
                    // Could be a time out.
                    Console::WriteLine("GC Notification not applicable.");
                    break;
                }
            }


            Thread::Sleep(500);
            // FinalExit is set to true right before 
            // the main thread cancelled notification. 
            if (finalExit)
            {
                break;
            }
        }
    }

The following code contains the OnFullGCApproachNotify method as called from the

WaitForFullGCProc method.

Public Shared Sub OnFullGCApproachNotify()
    Console.WriteLine("Redirecting requests.")

    ' Method that tells the request queuing   
    ' server to not direct requests to this server. 
    RedirectRequests()

    ' Method that provides time to  
    ' finish processing pending requests. 
    FinishExistingRequests()

    ' This is a good time to induce a GC collection 
    ' because the runtime will induce a ful GC soon. 
    ' To be very careful, you can check precede with a 
    ' check of the GC.GCCollectionCount to make sure 
    ' a full GC did not already occur since last notified.
    GC.Collect()
    Console.WriteLine("Induced a collection.")
End Sub
public static void OnFullGCApproachNotify()
{

    Console.WriteLine("Redirecting requests.");

    // Method that tells the request queuing   
    // server to not direct requests to this server. 
    RedirectRequests();

    // Method that provides time to  
    // finish processing pending requests. 
    FinishExistingRequests();

    // This is a good time to induce a GC collection 
    // because the runtime will induce a full GC soon. 
    // To be very careful, you can check precede with a 
    // check of the GC.GCCollectionCount to make sure 
    // a full GC did not already occur since last notified.
    GC.Collect();
    Console.WriteLine("Induced a collection.");

}
public:
    static void OnFullGCApproachNotify()
    {
        Console::WriteLine("Redirecting requests.");

        // Method that tells the request queuing 
        // server to not direct requests to this server.
        RedirectRequests();

        // Method that provides time to 
        // finish processing pending requests.
        FinishExistingRequests();

        // This is a good time to induce a GC collection 
        // because the runtime will induce a full GC soon. 
        // To be very careful, you can check precede with a 
        // check of the GC.GCCollectionCount to make sure 
        // a full GC did not already occur since last notified.
        GC::Collect();
        Console::WriteLine("Induced a collection.");

    }

The following code contains the OnFullGCApproachComplete method as called from the

WaitForFullGCProc method.

Public Shared Sub OnFullGCCompleteEndNotify()
    ' Method that informs the request queuing server 
    ' that this server is ready to accept requests again.
    AcceptRequests()
    Console.WriteLine("Accepting requests again.")
End Sub
public static void OnFullGCCompleteEndNotify()
{
    // Method that informs the request queuing server 
    // that this server is ready to accept requests again.
    AcceptRequests();
    Console.WriteLine("Accepting requests again.");
}
public:
    static void OnFullGCCompleteEndNotify()
    {
        // Method that informs the request queuing server 
        // that this server is ready to accept requests again.
        AcceptRequests();
        Console::WriteLine("Accepting requests again.");
    }

The following code contains the user methods that are called from the OnFullGCApproachNotify and OnFullGCCompleteNotify methods. The user methods redirect requests, finish existing requests, and then resume requests after a full garbage collection has occurred.

private static void RedirectRequests()
{
    // Code that sends requests 
    // to other servers. 

    // Suspend work.
    bAllocate = false;

}

private static void FinishExistingRequests()
{
    // Code that waits a period of time 
    // for pending requests to finish. 

    // Clear the simulated workload.
    load.Clear();

}

private static void AcceptRequests()
{
    // Code that resumes processing 
    // requests on this server. 

    // Resume work.
    bAllocate = true;

}
private:
    static void RedirectRequests()
    {
        // Code that sends requests 
        // to other servers. 

        // Suspend work.
        bAllocate = false;

    }

    static void FinishExistingRequests()
    {
        // Code that waits a period of time 
        // for pending requests to finish. 

        // Clear the simulated workload.
        load->Clear();

    }

    static void AcceptRequests()
    {
        // Code that resumes processing 
        // requests on this server. 

        // Resume work.
        bAllocate = true;
    }

The entire code sample is as follows:

Imports System
Imports System.Collections.Generic
Imports System.Threading
Imports Microsoft.VisualBasic



Class Program


    ' 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 

    Public Shared Sub OnFullGCApproachNotify()
        Console.WriteLine("Redirecting requests.")

        ' Method that tells the request queuing   
        ' server to not direct requests to this server. 
        RedirectRequests()

        ' Method that provides time to  
        ' finish processing pending requests. 
        FinishExistingRequests()

        ' This is a good time to induce a GC collection 
        ' because the runtime will induce a ful GC soon. 
        ' To be very careful, you can check precede with a 
        ' check of the GC.GCCollectionCount to make sure 
        ' a full GC did not already occur since last notified.
        GC.Collect()
        Console.WriteLine("Induced a collection.")
    End Sub 

    Public Shared Sub OnFullGCCompleteEndNotify()
        ' Method that informs the request queuing server 
        ' that this server is ready to accept requests again.
        AcceptRequests()
        Console.WriteLine("Accepting requests again.")
    End Sub 

    Public Shared Sub WaitForFullGCProc()

        While True 
            ' CheckForNotify is set to true and false in Main. 

            While checkForNotify
                ' Check for a notification of an approaching collection. 
                Dim s As GCNotificationStatus = GC.WaitForFullGCApproach
                If (s = GCNotificationStatus.Succeeded) Then
                    Console.WriteLine("GC Notifiction raised.")
                    OnFullGCApproachNotify()
                ElseIf (s = GCNotificationStatus.Canceled) Then
                    Console.WriteLine("GC Notification cancelled.")
                    Exit While 
                Else 
                    ' This can occur if a timeout period 
                    ' is specified for WaitForFullGCApproach(Timeout)  
                    ' or WaitForFullGCComplete(Timeout)   
                    ' and the time out period has elapsed. 
                    Console.WriteLine("GC Notification not applicable.")
                    Exit While 
                End If 

                ' Check for a notification of a completed collection.
                s = GC.WaitForFullGCComplete
                If (s = GCNotificationStatus.Succeeded) Then
                    Console.WriteLine("GC Notifiction raised.")
                    OnFullGCCompleteEndNotify()
                ElseIf (s = GCNotificationStatus.Canceled) Then
                    Console.WriteLine("GC Notification cancelled.")
                    Exit While 
                Else 
                    ' Could be a time out.
                    Console.WriteLine("GC Notification not applicable.")
                    Exit While 
                End If 

            End While
            Thread.Sleep(500)
            ' FinalExit is set to true right before   
            ' the main thread cancelled notification. 
            If finalExit Then 
                Exit While 
            End If 

        End While 
    End Sub 

    Private Shared Sub RedirectRequests()
        ' Code that sends requests 
        ' to other servers. 

        ' Suspend work.
        bAllocate = False 
    End Sub 

    Private Shared Sub FinishExistingRequests()
        ' Code that waits a period of time 
        ' for pending requests to finish. 

        ' Clear the simulated workload.
        load.Clear()

    End Sub 

    Private Shared Sub AcceptRequests()
        ' Code that resumes processing 
        ' requests on this server. 

        ' Resume work.
        bAllocate = True 
    End Sub 
End Class
using System;
using System.Collections.Generic;
using System.Threading;

namespace GCNotify
{
    class Program
    {

        // 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);
            }
        }




        public static void OnFullGCApproachNotify()
        {

            Console.WriteLine("Redirecting requests.");

            // Method that tells the request queuing   
            // server to not direct requests to this server. 
            RedirectRequests();

            // Method that provides time to  
            // finish processing pending requests. 
            FinishExistingRequests();

            // This is a good time to induce a GC collection 
            // because the runtime will induce a full GC soon. 
            // To be very careful, you can check precede with a 
            // check of the GC.GCCollectionCount to make sure 
            // a full GC did not already occur since last notified.
            GC.Collect();
            Console.WriteLine("Induced a collection.");

        }


        public static void OnFullGCCompleteEndNotify()
        {
            // Method that informs the request queuing server 
            // that this server is ready to accept requests again.
            AcceptRequests();
            Console.WriteLine("Accepting requests again.");
        }

        public static void WaitForFullGCProc()
        {
            while (true)
            {
                // CheckForNotify is set to true and false in Main. 
                while (checkForNotify)
                {
                    // Check for a notification of an approaching collection.
                    GCNotificationStatus s = GC.WaitForFullGCApproach();
                    if (s == GCNotificationStatus.Succeeded)
                    {
                        Console.WriteLine("GC Notifiction raised.");
                        OnFullGCApproachNotify();
                    }
                    else if (s == GCNotificationStatus.Canceled)
                    {
                        Console.WriteLine("GC Notification cancelled.");
                        break;
                    }
                    else
                    {
                        // This can occur if a timeout period 
                        // is specified for WaitForFullGCApproach(Timeout)  
                        // or WaitForFullGCComplete(Timeout)   
                        // and the time out period has elapsed. 
                        Console.WriteLine("GC Notification not applicable.");
                        break;
                    }

                    // Check for a notification of a completed collection.
                    s = GC.WaitForFullGCComplete();
                    if (s == GCNotificationStatus.Succeeded)
                    {
                        Console.WriteLine("GC Notifiction raised.");
                        OnFullGCCompleteEndNotify();
                    }
                    else if (s == GCNotificationStatus.Canceled)
                    {
                        Console.WriteLine("GC Notification cancelled.");
                        break;
                    }
                    else
                    {
                        // Could be a time out.
                        Console.WriteLine("GC Notification not applicable.");
                        break;
                    }
                }


                Thread.Sleep(500);
                // FinalExit is set to true right before   
                // the main thread cancelled notification. 
                if (finalExit)
                {
                    break;
                }
            }

        }

        private static void RedirectRequests()
        {
            // Code that sends requests 
            // to other servers. 

            // Suspend work.
            bAllocate = false;

        }

        private static void FinishExistingRequests()
        {
            // Code that waits a period of time 
            // for pending requests to finish. 

            // Clear the simulated workload.
            load.Clear();

        }

        private static void AcceptRequests()
        {
            // Code that resumes processing 
            // requests on this server. 

            // Resume work.
            bAllocate = true;

        }
    }
}
using namespace System;
using namespace System::Collections::Generic;
using namespace System::Threading;

namespace GCNotify
{
    ref class Program
    {
    private:
        // 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<array<Byte>^>^ load = gcnew List<array<Byte>^>();


    public:
        static void Main()
        {
            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 = gcnew Thread(gcnew 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(gcnew array<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);
            }
        }

    public:
        static void OnFullGCApproachNotify()
        {
            Console::WriteLine("Redirecting requests.");

            // Method that tells the request queuing 
            // server to not direct requests to this server.
            RedirectRequests();

            // Method that provides time to 
            // finish processing pending requests.
            FinishExistingRequests();

            // This is a good time to induce a GC collection 
            // because the runtime will induce a full GC soon. 
            // To be very careful, you can check precede with a 
            // check of the GC.GCCollectionCount to make sure 
            // a full GC did not already occur since last notified.
            GC::Collect();
            Console::WriteLine("Induced a collection.");

        }


    public:
        static void OnFullGCCompleteEndNotify()
        {
            // Method that informs the request queuing server 
            // that this server is ready to accept requests again.
            AcceptRequests();
            Console::WriteLine("Accepting requests again.");
        }

    public:
        static void WaitForFullGCProc()
        {
            while (true)
            {
                // CheckForNotify is set to true and false in Main. 
                while (checkForNotify)
                {
                    // Check for a notification of an approaching collection.
                    GCNotificationStatus s = GC::WaitForFullGCApproach();
                    if (s == GCNotificationStatus::Succeeded)
                    {
                        Console::WriteLine("GC Notifiction raised.");
                        OnFullGCApproachNotify();
                    }
                    else if (s == GCNotificationStatus::Canceled)
                    {
                        Console::WriteLine("GC Notification cancelled.");
                        break;
                    }
                    else
                    {
                        // This can occur if a timeout period 
                        // is specified for WaitForFullGCApproach(Timeout) 
                        // or WaitForFullGCComplete(Timeout) 
                        // and the time out period has elapsed.
                        Console::WriteLine("GC Notification not applicable.");
                        break;
                    }

                    // Check for a notification of a completed collection.
                    s = GC::WaitForFullGCComplete();
                    if (s == GCNotificationStatus::Succeeded)
                    {
                        Console::WriteLine("GC Notifiction raised.");
                        OnFullGCCompleteEndNotify();
                    }
                    else if (s == GCNotificationStatus::Canceled)
                    {
                        Console::WriteLine("GC Notification cancelled.");
                        break;
                    }
                    else
                    {
                        // Could be a time out.
                        Console::WriteLine("GC Notification not applicable.");
                        break;
                    }
                }


                Thread::Sleep(500);
                // FinalExit is set to true right before 
                // the main thread cancelled notification. 
                if (finalExit)
                {
                    break;
                }
            }
        }

    private:
        static void RedirectRequests()
        {
            // Code that sends requests 
            // to other servers. 

            // Suspend work.
            bAllocate = false;

        }

        static void FinishExistingRequests()
        {
            // Code that waits a period of time 
            // for pending requests to finish. 

            // Clear the simulated workload.
            load->Clear();

        }

        static void AcceptRequests()
        {
            // Code that resumes processing 
            // requests on this server. 

            // Resume work.
            bAllocate = true;
        }
    };
}

int main()
{
    GCNotify::Program::Main();
}

See Also

Other Resources

Garbage Collection

Change History

Date

History

Reason

July 2008

Added topic.

SP1 feature change.