Improve utillites

Add Canary

Author: LoneWandererProductions

MemoryManager.Core/AllocationPriority.cs

@@ -8,10 +8,24 @@
 
 namespace MemoryManager.Core
 {
+    /// <summary>
+    /// Priority of the Allocation, this can be used to determine the order in which allocations are made when multiple allocations are requested at the same time. This can be useful for optimizing performance and ensuring that critical allocations are made first.
+    /// </summary>
     public enum AllocationPriority
     {
+        /// <summary>
+        /// The critical Priority, these allocations are the most important and should be allocated first. They are likely to be used for critical game systems or performance-sensitive code.
+        /// </summary>
         Critical = 0,
+
+        /// <summary>
+        /// The normal, Priority, these allocations are important but not as critical as the critical ones. They may be used for general game logic or less performance-sensitive code.
+        /// </summary>
         Normal = 1,
+
+        /// <summary>
+        /// The low, Priority, these allocations are the least important and should be allocated last. They may be used for non-essential game features or background tasks that can tolerate delays in allocation.
+        /// </summary>
         Low = 2
     }
 }

MemoryManager.Core/BlobEntry.cs

@@ -2,7 +2,7 @@
  * COPYRIGHT:   See COPYING in the top level directory
  * PROJECT:     MemoryManager.Core
  * FILE:        BlobEntry.cs
- * PURPOSE:     Your file purpose here
+ * PURPOSE:     A struct representing metadata for a blob allocation within the memory arena, tracking its identifier, offset, size, allocation frame, and version for management and debugging purposes.
  * PROGRAMMER:  Peter Geinitz (Wayfarer)
  */
 
@@ -11,10 +11,29 @@ namespace MemoryManager.Core
     // A separate struct for tracking Blob metadata
     public struct BlobEntry
     {
+        /// <summary>
+        /// The identifier
+        /// </summary>
         public int Id;
+
+        /// <summary>
+        /// The offset
+        /// </summary>
         public int Offset;
+
+        /// <summary>
+        /// The size
+        /// </summary>
         public int Size;
+
+        /// <summary>
+        /// The allocation frame
+        /// </summary>
         public int AllocationFrame;
+
+        /// <summary>
+        /// The version
+        /// </summary>
         public byte Version;
     }
 }

MemoryManager.Lanes/MemoryCanary.cs

@@ -0,0 +1,117 @@
+/*
+ * COPYRIGHT:   See COPYING in the top level directory
+ * PROJECT:     MemoryManager.Lanes
+ * FILE:        MemoryCanary.cs
+ * PURPOSE:     Centralized unmanaged guard band validation with zero RELEASE overhead.
+ * PROGRAMMER:  Peter Geinitz (Wayfarer)
+ */
+
+using System.Runtime.CompilerServices;
+
+namespace MemoryManager.Lanes
+{
+    /// <summary>
+    /// Canary class provides a simple mechanism for detecting buffer overruns and underruns in debug builds by placing known "canary" values before and after user allocations. 
+    /// In release builds, the canary logic is completely stripped out to ensure zero overhead, 
+    /// making it an effective tool for catching memory corruption issues during development without impacting performance in production.
+    /// </summary>
+    internal static class MemoryCanary
+    {
+        /// <summary>
+        /// The size
+        /// </summary>
+        public const int Size = 4; // 4 bytes for a uint marker
+
+        /// <summary>
+        /// The magic
+        /// </summary>
+        private const uint Magic = 0xDEADBEEF;
+
+        /// <summary>
+        /// Calculates the total physical footprint needed in the allocator block pool.
+        /// </summary>
+        /// <param name="userSize">Size of the user.</param>
+        /// <returns></returns>
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public static int GetPhysicalSize(int userSize)
+        {
+#if DEBUG
+            return userSize + Size * 2;
+#else
+            return userSize;
+#endif
+        }
+
+        /// <summary>
+        /// Maps a raw physical block offset to a user-facing offset past the pre-canary.
+        /// </summary>
+        /// <param name="physicalOffset">The physical offset.</param>
+        /// <returns></returns>
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public static int GetUserOffset(int physicalOffset)
+        {
+#if DEBUG
+            return physicalOffset + Size;
+#else
+            return physicalOffset;
+#endif
+        }
+
+        /// <summary>
+        /// Maps a user data offset back to the absolute physical block start coordinate.
+        /// </summary>
+        /// <param name="userOffset">The user offset.</param>
+        /// <returns></returns>
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public static int GetPhysicalOffset(int userOffset)
+        {
+#if DEBUG
+            return userOffset - Size;
+#else
+            return userOffset;
+#endif
+        }
+
+        /// <summary>
+        /// Writes the invariant magic signatures around the user space allocation boundaries.
+        /// </summary>
+        /// <param name="buffer">The buffer.</param>
+        /// <param name="userOffset">The user offset.</param>
+        /// <param name="userSize">Size of the user.</param>
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public static unsafe void WriteGuardBands(nint buffer, int userOffset, int userSize)
+        {
+#if DEBUG
+            // Write Pre-Canary directly before the user offset space
+            *(uint*)(buffer + userOffset - Size) = Magic;
+            // Write Post-Canary directly at the tail index end of user size space
+            *(uint*)(buffer + userOffset + userSize) = Magic;
+#endif
+        }
+
+        /// <summary>
+        /// Inspects the boundaries to verify that no adjacent buffer underruns/overruns occurred.
+        /// </summary>
+        /// <param name="buffer">The buffer.</param>
+        /// <param name="userOffset">The user offset.</param>
+        /// <param name="userSize">Size of the user.</param>
+        /// <param name="handleId">The handle identifier.</param>
+        /// <exception cref="AccessViolationException">CRITICAL HEAP CORRUPTION DETECTED: Buffer boundary breach on Handle ID {handleId}. " +
+        ///                     $"Expected Canary: 0x{Magic:X}, Pre-Site: 0x{preCanary:X}, Post-Site: 0x{postCanary:X}</exception>
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public static unsafe void Validate(nint buffer, int userOffset, int userSize, int handleId)
+        {
+#if DEBUG
+            uint preCanary = *(uint*)(buffer + userOffset - Size);
+            uint postCanary = *(uint*)(buffer + userOffset + userSize);
+
+            if (preCanary != Magic || postCanary != Magic)
+            {
+                throw new AccessViolationException(
+                    $"CRITICAL HEAP CORRUPTION DETECTED: Buffer boundary breach on Handle ID {handleId}. " +
+                    $"Expected Canary: 0x{Magic:X}, Pre-Site: 0x{preCanary:X}, Post-Site: 0x{postCanary:X}");
+            }
+#endif
+        }
+    }
+}