Work on GC APIs

- Add APIs previsouly in Native.Runtime assembly.
- Add `Collect` and `GetTotalMemory` to follow .NET API.
- `Run` is now private and used in both the new APIs.
- Improve IntelliSense comments.
- Rework GC unit tests to take advantage of the new APIs in GC.
- Add new Unit test to cover `GetTotalMemory`.

Author: josesimoes

Tests/NFUnitTestGC/TestGC.cs

@@ -1,7 +1,8 @@
-// Licensed to the .NET Foundation under one or more agreements.
+// Licensed to the .NET Foundation under one or more agreements.
 // The .NET Foundation licenses this file to you under the MIT license.
 
 
+using System;
 using nanoFramework.TestFramework;
 
 namespace NFUnitTestGC
@@ -15,16 +16,14 @@ public void TestGCStress()
             int maxArraySize = 1024 * 32;
             object[] arrays = new object[600];
 
-            // Starting TestGCStress
-
             for (int loop = 0; loop < 100; loop++)
             {
                 OutputHelper.WriteLine($"Running iteration {loop}");
 
                 for (int i = 0; i < arrays.Length - 1;)
                 {
                     OutputHelper.WriteLine($"Alloc array of {maxArraySize} bytes @ pos {i}");
-                    arrays[i++] = new byte[maxArraySize]; ;
+                    arrays[i++] = new byte[maxArraySize];
 
                     OutputHelper.WriteLine($"Alloc array of 64 bytes @ pos {i}");
                     arrays[i++] = new byte[64];
@@ -37,8 +36,35 @@ public void TestGCStress()
                     arrays[i] = null;
                 }
             }
+        }
+
+        [TestMethod]
+        public void TestGetTotalMemory()
+        {
+            // create several objects
+            object[] objects = new object[100];
+
+            for (int i = 0; i < objects.Length; i++)
+            {
+                objects[i] = new object();
+            }
+
+            // get total memory
+            long totalMemory = GC.GetTotalMemory(false);
+            OutputHelper.WriteLine($"Total memory: {totalMemory} bytes");
+
+            // release objects
+            for (int i = 0; i < objects.Length; i++)
+            {
+                objects[i] = null;
+            }
+
+            // get total memory, forcing full collection
+            long totalMemoryAfterCollection = GC.GetTotalMemory(true);
+            OutputHelper.WriteLine($"Total memory: {totalMemoryAfterCollection} bytes");
 
-            // Completed TestGCStress
+            // check if memory was released
+            Assert.IsTrue(totalMemory > totalMemoryAfterCollection, "Memory was not released");
         }
     }
 }

Tests/NFUnitTestSystemLib/UnitTestGCTest.cs

@@ -9,6 +9,11 @@ namespace NFUnitTestSystemLib
     [TestClass]
     public class UnitTestGCTest
     {
+#pragma warning disable S1215 // this is intended to test the GC
+#pragma warning disable S1854 // this is intended to test the GC
+#pragma warning disable S2696 // this is intended to test the GC
+#pragma warning disable S3971 // this is intended to test the GC
+
         internal class FinalizeObject
         {
             public static FinalizeObject m_currentInstance = null;
@@ -54,17 +59,20 @@ public void SystemGC1_Test()
             /// 6. Verify that object has been collected
             /// </summary>
             ///
-            // Tests ReRegisterForFinalize
-            // Create a FinalizeObject.
+
+            OutputHelper.WriteLine("Tests ReRegisterForFinalize");
+            OutputHelper.WriteLine("Create a FinalizeObject.");
+
             FinalizeObject mfo = new FinalizeObject();
             m_hasFinalized1 = false;
             m_hasFinalized2 = false;
 
             // Release reference
+            OutputHelper.WriteLine("Release reference");
             mfo = null;
 
-            // Allow GC
-            GC.WaitForPendingFinalizers();
+            OutputHelper.WriteLine("Allow GC");
+            GC.Collect();
 
             int sleepTime = 1000;
             int slept = 0;
@@ -85,10 +93,10 @@ public void SystemGC1_Test()
             // FinalizeObject.m_currentInstance field.  Setting this value
             // to null and forcing another garbage collection will now
             // cause the object to Finalize permanently.
-            // Reregister and allow for GC
-            FinalizeObject.m_currentInstance = null;
 
-            GC.WaitForPendingFinalizers();
+            OutputHelper.WriteLine("Reregister and allow for GC");
+            FinalizeObject.m_currentInstance = null;
+            GC.Collect();
 
             sleepTime = 1000;
             slept = 0;
@@ -119,26 +127,27 @@ public void SystemGC2_Test()
             /// 6. Verify that object has not been collected
             /// </summary>
             ///
-            // Tests SuppressFinalize
-            // Create a FinalizeObject.
+
+            OutputHelper.WriteLine("Tests SuppressFinalize");
+            OutputHelper.WriteLine("Create a FinalizeObject");
             FinalizeObject mfo = new FinalizeObject();
             m_hasFinalized1 = false;
             m_hasFinalized2 = false;
 
-            // Releasing
+            OutputHelper.WriteLine("Releasing");
             GC.SuppressFinalize(mfo);
             mfo = null;
 
-            // Allow GC
-            GC.WaitForPendingFinalizers();
+            OutputHelper.WriteLine("Allow GC");
+            GC.Collect();
 
             int sleepTime = 1000;
             int slept = 0;
 
             while (!m_hasFinalized1 && slept < sleepTime)
             {
                 // force GC run caused by memory allocation
-                var dummyArray = new byte[1024 * 1024 * 1];
+                _ = new byte[1024 * 1024 * 1];
 
                 System.Threading.Thread.Sleep(10);
                 slept += 10;
@@ -161,59 +170,35 @@ public void SystemGC3_Test()
             /// </summary>
             ///
 
-            // Tests WaitForPendingFinalizers, dependant on test 1
-            // will auto-fail if test 1 fails.
             OutputHelper.Write("Tests WaitForPendingFinalizers, dependant on test 1");
-            OutputHelper.WriteLine("will auto-fail if test 1 fails.");
+            OutputHelper.WriteLine("will fail if test 1 fails.");
 
-            Assert.IsTrue(m_Test1Result);
+            Assert.IsTrue(m_Test1Result, "Can't run this test as SystemGC1_Test has failed.");
 
-            // Create a FinalizeObject.
+            OutputHelper.WriteLine("Create a FinalizeObject");
             FinalizeObject mfo = new FinalizeObject();
             m_hasFinalized1 = false;
             m_hasFinalized2 = false;
 
-            // Releasing
+            OutputHelper.WriteLine("Releasing");
             mfo = null;
 
-            int sleepTime = 1000;
-            int slept = 0;
-
-            while (!m_hasFinalized1 && slept < sleepTime)
-            {
-                // force GC run caused by memory allocation
-                var dummyArray = new byte[1024 * 1024 * 1];
-
-                System.Threading.Thread.Sleep(10);
-                slept += 10;
-            }
-
-            OutputHelper.WriteLine($"GC took {slept}");
-
-            // Wait for GC
+            OutputHelper.WriteLine("Wait for GC");
+            GC.Collect();
             GC.WaitForPendingFinalizers();
 
-            // Releasing again
+            OutputHelper.WriteLine("Releasing again");
             FinalizeObject.m_currentInstance = null;
 
-            sleepTime = 1000;
-            slept = 0;
-
-            while (!m_hasFinalized2 && slept < sleepTime)
-            {
-                // force GC run caused by memory allocation
-                var dummyArray = new byte[1024 * 1024 * 1];
-
-                System.Threading.Thread.Sleep(10);
-                slept += 10;
-            }
-
-            OutputHelper.WriteLine($"GC took {slept}");
-
-            // Wait for GC
+            OutputHelper.WriteLine("Wait for GC");
+            GC.Collect();
             GC.WaitForPendingFinalizers();
 
             Assert.IsTrue(m_hasFinalized2);
         }
     }
+#pragma warning restore S1215 // "GC.Collect" should not be called
+#pragma warning restore S1854 // Unused assignments should be removed
+#pragma warning restore S2696 // Instance members should not write to "static" fields
+#pragma warning restore S3971 // "GC.SuppressFinalize" should not be called
 }

nanoFramework.CoreLibrary/System/GC.cs

@@ -1,39 +1,79 @@
-// Licensed to the .NET Foundation under one or more agreements.
+// Licensed to the .NET Foundation under one or more agreements.
 // The .NET Foundation licenses this file to you under the MIT license.
 
+using System.Runtime.CompilerServices;
+
 namespace System
 {
-    using Runtime.CompilerServices;
-
     /// <summary>
     /// Controls the system garbage collector, a service that automatically reclaims unused memory.
     /// </summary>
     public static class GC
     {
+#pragma warning disable S4200 // Native methods should be wrapped
+
+        /// <summary>
+        /// Enables or disables the output of garbage collection messages.
+        /// </summary>
+        /// <param name="enable"><see langword="true"/> to enable the output of GC messages; otherwise, <see langword="false"/>.</param>
+        /// <remarks>
+        /// <para>
+        /// Enabling GC messages may not always result in output, depending on the target build options.
+        /// For example, RTM builds, which remove all non-essential features, may not output these messages.
+        /// </para>
+        /// <para>
+        /// This method is specific of .NET nanoFramework implementation. There is no equivalent in full .NET API.
+        /// </para>
+        /// </remarks>
         [MethodImpl(MethodImplOptions.InternalCall)]
-        private static extern bool AnyPendingFinalizers();
+        public static extern void EnableGCMessages(bool enable);
 
         /// <summary>
-        /// Suspends the current thread until the thread that is processing the queue of finalizers has emptied that queue.
+        /// Retrieves the heap size excluding fragmentation. For example if the total GC heap size is 1MB and fragmentation, ie, space taken up by free objects, takes up 400kB, this API would report 600kB. A parameter indicates whether this method can wait a short interval before returning, to allow the system to collect garbage and finalize objects.
         /// </summary>
-        public static void WaitForPendingFinalizers()
-        {
-            while (AnyPendingFinalizers()) Threading.Thread.Sleep(10);
-        }
+        /// <param name="forceFullCollection"><see langword="true"/> to indicate that this method can wait for garbage collection and heap compaction to occur before returning; otherwise, <see langword="false"/>.</param>
+        /// <returns>The heap size, in bytes, excluding fragmentation.</returns>
+        public static long GetTotalMemory(bool forceFullCollection) => Run(forceFullCollection);
 
         /// <summary>
-        /// Requests that the system not call the finalizer for the specified object.
+        /// Requests that the system call the finalizer for the specified object for which <see cref="SuppressFinalize"/> has previously been called.
         /// </summary>
-        /// <param name="obj">The object that a finalizer must not be called for. </param>
+        /// <param name="obj">The object that a finalizer must be called for.</param>
+        /// <exception cref="ArgumentNullException"><paramref name="obj"/> is <see langword="null"/>.</exception>
         [MethodImpl(MethodImplOptions.InternalCall)]
-        public static extern void SuppressFinalize(Object obj);
+        public static extern void ReRegisterForFinalize(object obj);
+
+        /// <summary>
+        /// Forces an immediate garbage collection of all generations.
+        /// </summary>
+        /// <remarks>
+        /// Use this method to try to reclaim all memory that is inaccessible. It performs a blocking garbage collection of all generations.
+        /// All objects, regardless of how long they have been in memory, are considered for collection; however, objects that are referenced in managed code are not collected. Use this method to force the system to try to reclaim the maximum amount of available memory.
+        /// </remarks>
+        public static void Collect() => Run(true);
 
         /// <summary>
-        /// Requests that the system call the finalizer for the specified object for which SuppressFinalize has previously been called.
+        /// Requests that the common language runtime not call the finalizer for the specified object.
         /// </summary>
-        /// <param name="obj">The object that a finalizer must be called for. </param>
+        /// <param name="obj">The object whose finalizer must not be executed.</param>
+        /// <exception cref="ArgumentNullException"><paramref name="obj"/> is <see langword="null"/>.</exception>
         [MethodImpl(MethodImplOptions.InternalCall)]
-        public static extern void ReRegisterForFinalize(Object obj);
+        public static extern void SuppressFinalize(object obj);
 
+        /// <summary>
+        /// Suspends the current thread until the thread that is processing the queue of finalizers has emptied that queue.
+        /// </summary>
+        public static void WaitForPendingFinalizers()
+        {
+            while (AnyPendingFinalizers()) Threading.Thread.Sleep(10);
+        }
+
+#pragma warning restore S4200 // Native methods should be wrapped
+
+        [MethodImpl(MethodImplOptions.InternalCall)]
+        private static extern bool AnyPendingFinalizers();
+
+        [MethodImpl(MethodImplOptions.InternalCall)]
+        private static extern uint Run(bool compactHeap);
     }
 }