add padding

Author: LoneWandererProductions

MemoryManager.Core/MemoryCanary.cs

@@ -6,6 +6,7 @@
  * PROGRAMMER:  Peter Geinitz (Wayfarer)
  */
 
+using System;
 using System.Runtime.CompilerServices;
 
 namespace MemoryManager.Core
@@ -14,9 +15,15 @@ namespace MemoryManager.Core
     /// 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.
+    /// It additionally acts as an alignment boundary engine, snapping unmanaged pointers cleanly to hardware memory channels.
     /// </summary>
     public static class MemoryCanary
     {
+        /// <summary>
+        /// The byte alignment requirement boundary (Must be a power of two, e.g., 16, 32, 64)
+        /// </summary>
+        private const int Alignment = 16;
+
         /// <summary>
         /// The size
         /// </summary>
@@ -27,49 +34,52 @@ public static class MemoryCanary
         /// </summary>
         private const uint Magic = 0xDEADBEEF;
 
+        /// <summary>
+        /// Pre-calculated front window padding size required to fit the pre-canary and maintain power-of-two alignment
+        /// </summary>
+#if DEBUG
+        private static readonly int FrontPadding = (Size + (Alignment - 1)) & ~(Alignment - 1);
+#else
+        private static readonly int FrontPadding = 0;
+#endif
+
         /// <summary>
         /// Calculates the total physical footprint needed in the allocator block pool.
         /// </summary>
         /// <param name="userSize">Size of the user.</param>
-        /// <returns></returns>
+        /// <returns>Total block allocation size required, rounded up to the nearest alignment multiple.</returns>
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
         public static int GetPhysicalSize(int userSize)
         {
 #if DEBUG
-            return userSize + Size * 2;
+            // Raw physical size needs space for front tracking layout padding, user data payload, and post-canary trail bytes
+            int rawSize = FrontPadding + userSize + Size;
+            return (rawSize + (Alignment - 1)) & ~(Alignment - 1);
 #else
-            return userSize;
+            return (userSize + (Alignment - 1)) & ~(Alignment - 1);
 #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>
+        /// <returns>Aligned offset position where user data begins.</returns>
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
         public static int GetUserOffset(int physicalOffset)
         {
-#if DEBUG
-            return physicalOffset + Size;
-#else
-            return physicalOffset;
-#endif
+            return physicalOffset + FrontPadding;
         }
 
         /// <summary>
         /// Maps a user data offset back to the absolute physical block start coordinate.
         /// </summary>
         /// <param name="userOffset">The user offset.</param>
-        /// <returns></returns>
+        /// <returns>Absolute start address index of the complete tracking memory block pool chunk.</returns>
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
         public static int GetPhysicalOffset(int userOffset)
         {
-#if DEBUG
-            return userOffset - Size;
-#else
-            return userOffset;
-#endif
+            return userOffset - FrontPadding;
         }
 
         /// <summary>
@@ -97,7 +107,7 @@ public static unsafe void WriteGuardBands(nint buffer, int userOffset, int userS
         /// <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>
+        ///                      $"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)
         {

MemoryManager.Tests/BlobManagerTests.cs

@@ -16,9 +16,6 @@ namespace MemoryManager.Tests
     [TestClass]
     public class BlobManagerTests
     {
-        /// <summary>
-        /// BLOBs the manager allocate free and compact works correctly.
-        /// </summary>
         /// <summary>
         /// BLOBs the manager allocate free and compact works correctly.
         /// </summary>
@@ -38,10 +35,9 @@ public void BlobManager_AllocateFreeAndCompact_WorksCorrectly()
                 var h2 = blobManager.Allocate(100);
                 var h3 = blobManager.Allocate(100);
 
-                // Dynamically detect canary size from the first block's user offset shift
-                int canarySize = blobManager.GetEntry(h1).Offset; // 4 bytes in DEBUG, 0 bytes in RELEASE
-                int totalCanaryOverhead = 3 * (canarySize * 2);   // 3 blocks * 2 canaries each
-                int expectedFreeSpace = capacity - (300 + totalCanaryOverhead);
+                // Query the core alignment engine directly to determine the true physical footprint
+                int physicalBlockSize = MemoryCanary.GetPhysicalSize(100);
+                int expectedFreeSpace = capacity - (3 * physicalBlockSize);
 
                 Assert.AreEqual(expectedFreeSpace, blobManager.FreeSpace(), $"Should have exactly {expectedFreeSpace} bytes free.");
 
@@ -83,7 +79,11 @@ public void Performance_FastLane_Vs_LinearLane_Showdown()
         {
             const int count = 50000;
             const int size = 32; // 32-byte structs (e.g., matrices, vectors)
-            const int capacity = count * size * 2; // Plenty of room
+
+            // Calculate capacity using the true aligned physical size, 
+            // and add a small 4KB cushion padding to accommodate non-reclaiming warmup bumps
+            int physicalSize = MemoryCanary.GetPhysicalSize(size);
+            int capacity = (count * physicalSize) + 4096;
 
             // Both lanes require a SlowLane reference in their constructors
             using var slowLane = new SlowLane(capacity);
@@ -142,9 +142,6 @@ public void Performance_FastLane_Vs_LinearLane_Showdown()
             Trace.WriteLine("===== DEALLOCATION SPEED (50,000 objects) =====");
             Trace.WriteLine($"LinearLane (Bump) : {linearFreeTicks:N0} ticks");
             Trace.WriteLine($"FastLane (List)   : {fastFreeTicks:N0} ticks");
-
-            // The Bump allocator should absolutely destroy the Free-List in allocation speed
-            // because it doesn't have to loop through the _freeBlocks array!
         }
     }
 }

README.md

@@ -50,12 +50,6 @@ To move this system out of the prototyping phase and into a hardened, production
 * **Current State:** When compaction triggers, the compactor engine allocates an entirely new unmanaged heap block via `Marshal.AllocHGlobal` and slides all survivors over via memory block copying. For massive heaps (e.g., 512MB+), this causes noticeable block stutters (latency spikes) and temporarily forces a **double memory footprint**.
 * **Production Fix:** Implement an **Incremental/Phased Compactor** that only relocates a small chunk of fragmented blocks per frame tick, or enforce strict zero-compaction rules where arenas are completely cleared and cycled out at deterministic boundaries (e.g., scene changes).
 
-### 3. Hardware Memory Alignment Blindness
-* **Current State:** The bump allocators currently increment layouts directly by byte size (`_nextFreeOffset += size`). If a user allocates an odd structural layout (e.g., a 7-byte struct), subsequent items are placed on unaligned memory addresses, causing the CPU to fetch multiple cache-lines for single read instructions, tanking cache line efficiency.
-* **Production Fix:** Force all lane offsets to snap cleanly to hardware alignment boundaries (e.g., 16-byte, 32-byte, or 64-byte boundaries for SIMD alignment) using power-of-two bitwise masking layout constraints:
-  ```csharp
-  alignedOffset = (offset + (alignment - 1)) & ~(alignment - 1);
-
 ---
 
 ## 🧩 Config Presets & Advanced Usage