l4 evict and swiss api improve

src/Nitload.Common/HighPerformance/Memory/L4.CacheLine.cs

@@ -6,6 +6,7 @@
 // -----------------------------------------------------------------------------
 
 using System.Runtime.InteropServices;
+using System.Xml.Serialization;
 
 namespace Nitload.Common.HighPerformance.Memory
 {
@@ -27,10 +28,38 @@ namespace Nitload.Common.HighPerformance.Memory
 
             internal const uint MaxBufferSize = 0xFFFFFFFF - 64U;
 
-            [FieldOffset(16)] internal AllocationState State;
+            [FieldOffset(31)] internal AllocationState State;
 
             public static uint SizeOf { get; } = (uint)Unsafe.SizeOf<CacheLineMetadata>();
 
+            /// <summary>
+            ///   only available in L4.Predict()
+            /// </summary>
+            public void CheckCount()
+            {
+                uint count = Volatile.Read(ref ConsumeCount);
+                if (ushort.MaxValue < count)
+                {
+                    uint delta = unchecked(0u - count);
+                    _ = Interlocked.Add(ref ConsumeCount, delta);
+                    _ = Interlocked.Add(ref PredictCount, delta);
+                }
+            }
+
+            public void IncreaseConsumeCount()
+            {
+                unchecked {
+                    _ = Interlocked.Increment(ref ConsumeCount);
+                }
+            }
+
+            public void IncreasePredictCount()
+            {
+                unchecked {
+                    _ = Interlocked.Increment(ref PredictCount);
+                }
+            }
+
             #region tlsf linked list
 
             [FieldOffset(0)] public short NextLevel;
@@ -42,8 +71,15 @@ namespace Nitload.Common.HighPerformance.Memory
 
             #region buffer
 
-            [FieldOffset(8)] public uint PositionMask;
+            [FieldOffset(8)] public nuint Position;
-            [FieldOffset(12)] public uint SizeMask;
+            [FieldOffset(16)] public uint SizeMask;
+
+            #endregion
+
+            #region count
+
+            [FieldOffset(20)] public uint PredictCount;
+            [FieldOffset(24)] public uint ConsumeCount;
 
         #endregion
         }

src/Nitload.Common/HighPerformance/Memory/L4.Map.cs

@@ -72,8 +72,8 @@ namespace Nitload.Common.HighPerformance.Memory
             CacheLineMetadata* metadata = (CacheLineMetadata*)handle;
 
             // process metadata, unfinished
-            uint offset = metadata->PositionMask;
+            ulong offset = metadata->Position;
-            nuint address = /*base ptr + */ offset;
+            nuint address = /*base ptr + */ (nuint)offset;
             _ = Interlocked.Decrement(ref _predict_count);
 
             return new Handle(address, (nuint)handle);

src/Nitload.Common/HighPerformance/Memory/L4.Predict.cs

@@ -16,10 +16,96 @@ namespace Nitload.Common.HighPerformance.Memory
     public unsafe partial class L4
     {
 
+        private int _active_line_count;
+
+        private int _last_evict_pos;
+
         internal partial int Predict()
         {
-            throw new NotImplementedException();
+            if (!TryGetCurrentPredictor(out IL4Predictor? p)) {
+                return 0;
+            }
+            int total_count = 0, count;
+            Span<L4.AddressSource> as_sp = stackalloc L4.AddressSource[4];
+            SwissEnumerator e = _addressMap.GetWriteBufferEnumerator();
+            Predict:
+            while ((count = p.PredictMission(in as_sp)) > 0)
+            {
+                for (int i = 0; i < count; i++)
+                {
+                    if (_addressMap.TryGetWrite(as_sp[i], out ulong map_handle_adr))
+                    {
+                        L4.CacheLineMetadata* map_handle = (L4.CacheLineMetadata*)map_handle_adr;
+                        map_handle->IncreasePredictCount();
+                        map_handle->CheckCount();
+                    } else
+                    {
+                        uint size = as_sp[i].Size;
+                        int handle_idx = _bufferAllocator.Alloc(size);
+                        L4.CacheLineMetadata* handle = _bufferAllocator.MetadataAt(handle_idx);
+                        p.Prefetch(as_sp[i], handle->Position, handle->SizeMask);
+                        if (!_addressMap.TryAddOrSet(as_sp[i], (ulong)handle)) {
+                            throw new InvalidOperationException();
+                        }
+                        _active_line_count++;
+
+                        if (_active_line_count >= MaxActiveCacheLineCount)
+                        {
+                            int retry = 0;
+                            const int max_retry = 3;
+                            for (; retry < max_retry && EvictOnce(ref e); retry++) {
+                                e = _addressMap.GetWriteBufferEnumerator(_last_evict_pos);
+                            }
+                            if (retry >= max_retry) {
+                                throw new OverflowException("Evict failed, maybe all cache lines are in use.");
+                            }
+                            _active_line_count--;
+                        }
+                    }
+                }
+                total_count += count;
+                if (total_count >= 2048)
+                {
+                    _ = Interlocked.Add(ref _predict_count, total_count);
+                    _last_evict_pos = e.CurrentOffset;
+                    return total_count;
+                }
+            }
+            if (MoveNextPredictor())
+            {
+                _ = TryGetCurrentPredictor(out p);
+                goto Predict;
+            }
+            _ = Interlocked.Add(ref _predict_count, total_count);
+            _last_evict_pos = e.CurrentOffset;
+            return total_count;
+        }
+
+        private bool EvictOnce(
+                     ref SwissEnumerator e
+        )
+        {
+            while (e.MoveNext())
+            {
+                (AddressSource source, ulong cache_head_ptr) = e.Current;
+                L4.CacheLineMetadata* handle = (L4.CacheLineMetadata*)cache_head_ptr;
+                if (Volatile.Read(ref handle->ConsumeCount) == Volatile.Read(ref handle->ConsumeCount))
+                {
+                    // evict
+                    _ = _addressMap.TryRemove(source, out _);
+                    _bufferAllocator.Free(handle);
+                    return true;
+                }
+            }
+            return false;
         }
 
     }
 }
+
+// Eviction follow-up:
+// 1. Compare ConsumeCount with PredictCount; reset both on TLSF slot reuse and count new predictions.
+// 2. Fix retry/result handling; decrement _active_line_count only after a successful eviction.
+// 3. Correct TLSF reverse-slab pointer validation before freeing metadata pointers.
+// 4. Defer TLSF Free until retired published buffers and outstanding handles can no longer reference the line.
+// 5. Add Swiss TryRemoveAt(offset) to tombstone the enumerated slot without hashing and probing again.

src/Nitload.Common/HighPerformance/Memory/L4.PredictorQueue.cs

@@ -16,7 +16,6 @@ namespace Nitload.Common.HighPerformance.Memory
     public partial class L4
     {
 
-        private readonly IL4Predictor[] _ring = new IL4Predictor[256];
         private volatile int _consume;
         private volatile int _enter;
         private volatile int _predict;
@@ -61,6 +60,12 @@ namespace Nitload.Common.HighPerformance.Memory
             }
         }
 
+        internal bool MoveNextPredictor()
+        {
+            int cur = Interlocked.Increment(ref _predict);
+            return cur < _enter;
+        }
+
         internal void RegistPredictor(
                       IL4Predictor predictor
         )
@@ -69,18 +74,25 @@ namespace Nitload.Common.HighPerformance.Memory
                 return;
             }
             SpinWait sp = new();
+
+            wait_for_spare:
+            WaitForSpare();
+
             while (Interlocked.CompareExchange(ref _queue_sync, 1, 0) != 0) {
                 sp.SpinOnce();
             }
+            if (_enter - _consume >= PredictorRingCapacity)
+            {
+                _ = Interlocked.Exchange(ref _queue_sync, 0);
+                goto wait_for_spare;
+            }
 
-            WaitForSpare();
-
-            _consume++;
             try
             {
                 unchecked
                 {
-                    byte idx = (byte)_consume;
+                    byte idx = (byte)_enter;
+                    _enter++;
                     _ring[idx] = predictor;
                 }
             }
@@ -90,12 +102,28 @@ namespace Nitload.Common.HighPerformance.Memory
             }
         }
 
+        internal bool TryGetCurrentPredictor(
+                      out IL4Predictor predictor
+        )
+        {
+            int cur = _predict;
+            if (cur >= _enter)
+            {
+                predictor = default!;
+                return false;
+            }
+            unchecked
+            {
+                predictor = _ring[(byte)cur];
+                return true;
+            }
+        }
+
         private void WaitForSpare()
         {
             int spin_count = 0;
 
-            // wait until the queue has space
+            while (_enter - _consume >= PredictorRingCapacity)
-            while (_enter - _consume >= 256)
             {
                 switch (spin_count)
                 {

src/Nitload.Common/HighPerformance/Memory/L4.SwissTable.cs

@@ -39,8 +39,9 @@ namespace Nitload.Common.HighPerformance.Memory
         public struct AddressSource : IEquatable<AddressSource>
         {
 
+            public uint Description;
+            public uint Size;
             public ulong Address;
-            public ulong Description;
 
             public readonly bool Equals(
                                  AddressSource other
@@ -96,16 +97,18 @@ namespace Nitload.Common.HighPerformance.Memory
         }
 
         internal unsafe struct SwissEnumerator(
-                               byte* buffer
+                               byte* buffer,
+                               int begins_at = 0
         )
         {
 
             private readonly SwissBucket* _buckets = (SwissBucket*)(buffer + IdealCount);
             private readonly Vector128<byte>* _control_bytes = (Vector128<byte>*)buffer;
-            private int _current_group;
+            private bool _group_loaded = false;
-            private int _current_mask;
+            private int _visited_group = 0;
-            private int _current_offset;
+            private int _current_group = (begins_at / BucketCapacity) & (GroupCount - 1);
-            private bool _group_loaded;
+            private int _current_mask = 0;
+            private int _current_offset = 0;
 
             public (AddressSource key, ulong value) Current
             {
@@ -118,9 +121,11 @@ namespace Nitload.Common.HighPerformance.Memory
                 }
             }
 
+            public readonly int CurrentOffset => (_current_group * BucketCapacity) + _current_offset;
+
             public bool MoveNext()
             {
-                while (_current_group < GroupCount)
+                while (_visited_group < GroupCount)
                 {
                     if (!_group_loaded)
                     {
@@ -141,7 +146,8 @@ namespace Nitload.Common.HighPerformance.Memory
                         return true;
                     }
 
-                    _current_group++;
+                    _current_group = (_current_group + 1) & (GroupCount - 1);
+                    _visited_group++;
                     _group_loaded = false;
                 }
                 return false;
@@ -217,6 +223,22 @@ namespace Nitload.Common.HighPerformance.Memory
                 throw new NotImplementedException("The Swiss backend is not implemented for this ISA.");
             }
 
+            /// <summary>
+            ///   Reads the inactive write buffer. The caller must serialize this query with all
+            ///   writes.
+            /// </summary>
+            public bool TryGetWrite(
+                        AddressSource key,
+                        out ulong value
+            )
+            {
+                if (Sse42.IsSupported) {
+                    return SwissReaderX86.TryGet(_buffer_write, key, out value);
+                }
+
+                throw new NotImplementedException("The Swiss backend is not implemented for this ISA.");
+            }
+
             public void TryRehash()
             {
                 if (_delete_count < 2048)
@@ -233,8 +255,8 @@ namespace Nitload.Common.HighPerformance.Memory
                         while (e.MoveNext())
                         {
                             (AddressSource key, ulong value) = e.Current;
-                            if (!SwissWriterX86.TryAddOrSet(_buffer_write, key, value, ref _delete_count))
+                            if (!SwissWriterX86.TryAddOrSet(_buffer_write, key, value,
-                            {
+                                                            ref _delete_count)) {
                                 throw new InvalidOperationException("The Swiss table could not fit all active entries during rehash.");
                             }
                         }
@@ -261,7 +283,8 @@ namespace Nitload.Common.HighPerformance.Memory
             {
                 if (Sse42.IsSupported)
                 {
-                    return SwissWriterX86.TryRemove(_buffer_write, key, out value, ref _delete_count);
+                    return SwissWriterX86.TryRemove(_buffer_write, key, out value,
+                                                    ref _delete_count);
                 } else
                 {
                     throw new NotImplementedException("The Swiss backend is not implemented for this ISA.");
@@ -276,6 +299,14 @@ namespace Nitload.Common.HighPerformance.Memory
                 return new SwissTable(buffers);
             }
 
+            // Enumerates the write buffer; the caller must serialize writers and prevent swaps.
+            internal readonly SwissEnumerator GetWriteBufferEnumerator(
+                                              int begins_at = 0
+            )
+            {
+                return new SwissEnumerator(_buffer_write, begins_at);
+            }
+
             private static void InitializeBuffer(
                                 byte* buffer
             )

src/Nitload.Common/HighPerformance/Memory/L4.Tlsf.cs

@@ -5,27 +5,29 @@
 // SPDX-License-Identifier: MIT
 // -----------------------------------------------------------------------------
 
-using Nitload.Common.HighPerformance.ProcessorAbstraction;
-using System;
-using System.Collections.Generic;
-using System.Linq;
 using System.Numerics;
-using System.Runtime.InteropServices;
+using System.Reflection.Metadata;
-using System.Text;
-using System.Threading.Tasks;
 
 namespace Nitload.Common.HighPerformance.Memory
 {
     public partial class L4
     {
 
+        /// <summary>
+        ///   L4-specific TLSF allocator whose metadata nodes also serve as cache-line headers.
+        /// </summary>
+        /// <remarks>
+        ///   Payload occupies the first arena region; a fixed metadata slab follows it and is
+        ///   carved backward from its aligned high end. Handle 0 is the sentinel, and positive
+        ///   handles are metadata slot indices. This layout is intentionally coupled to L4.
+        /// </remarks>
         private unsafe struct TLSF
         {
 
-            public const int MaxCacheLineCount = 8192;
+            public const int MaxCacheLineCount = MaxActiveCacheLineCount;
 
             public static readonly nuint RequestedAllocation =
-                    ((nuint)MaxCacheLineCount + 1u) * CacheLineMetadata.SizeOf;
+                    (((nuint)MaxCacheLineCount + 1u) * CacheLineMetadata.SizeOf) + CacheLineMetadata.SizeOf - 1u;
             private readonly CacheLineMetadata* _spareMemory;
             private readonly int _align;
             private readonly int _maxLevel;
@@ -52,12 +54,16 @@ namespace Nitload.Common.HighPerformance.Memory
 
                 // _bucket = new short[GetLevel(_maxAllocSize) + 2];
                 _bucket[63] = (short)(GetLevel(_maxAllocSize) + 2);
-                _spareMemory = (CacheLineMetadata*)(ulong)(_basePtr + _totalSize);
+
+                // Metadata occupies the reservation after payload: handle 0 is the sentinel, and handles 1..MaxCacheLineCount are carved backward from the aligned high end until the slab is full.
+                nuint metadataRegionEnd = (nuint)externalPointer + byteSize + RequestedAllocation;
+                nuint alignedMetadataEnd = metadataRegionEnd & ~((nuint)CacheLineMetadata.SizeOf - 1u);
+                _spareMemory = (CacheLineMetadata*)(alignedMetadataEnd - CacheLineMetadata.SizeOf);
                 _metadataEnd = 0;
 
                 // init spare memory node
 
-                _spareMemory->PositionMask = 0;
+                _spareMemory->Position = (nuint)(ulong)_basePtr;
                 _spareMemory->SizeMask = _totalSize;
                 _spareMemory->NextLevel = 0;
                 _spareMemory->NextNear = 0;
@@ -66,7 +72,15 @@ namespace Nitload.Common.HighPerformance.Memory
             }
 
             [MethodImpl(MethodImplOptions.AggressiveInlining)]
-            private int GetLevel(
+            internal readonly CacheLineMetadata* MetadataAt(
+                                                 int handle
+            )
+            {
+                return _spareMemory - handle;
+            }
+
+            [MethodImpl(MethodImplOptions.AggressiveInlining)]
+            private readonly int GetLevel(
                                  uint size
             )
             {
@@ -93,11 +107,11 @@ namespace Nitload.Common.HighPerformance.Memory
                 // remove from position chain
                 short prevNearIdx = node->PreviousNear;
                 short nextNearIdx = node->NextNear;
-                CacheLineMetadata* prevNear = &_spareMemory[prevNearIdx];
+                CacheLineMetadata* prevNear = MetadataAt(prevNearIdx);
                 prevNear->NextNear = nextNearIdx;
                 if (nextNearIdx != 0)
                 {
-                    CacheLineMetadata* nextNear = &_spareMemory[nextNearIdx];
+                    CacheLineMetadata* nextNear = MetadataAt(nextNearIdx);
                     nextNear->PreviousNear = prevNearIdx;
                 } else
                 {
@@ -106,7 +120,7 @@ namespace Nitload.Common.HighPerformance.Memory
                 node->PreviousNear = 0;
                 node->NextNear = 0;
 
-                node->PositionMask = 0;
+                node->Position = (nuint)(ulong)_basePtr;
                 node->SizeMask = 0;
                 node->State = AllocationState.SpareOrCollect;
                 node->PreviousLevel = 0;
@@ -114,7 +128,7 @@ namespace Nitload.Common.HighPerformance.Memory
                 short nextIdx = _spareMemory->NextLevel;
                 if (nextIdx != 0)
                 {
-                    CacheLineMetadata* next = &_spareMemory[nextIdx];
+                    CacheLineMetadata* next = MetadataAt(nextIdx);
                     next->PreviousLevel = nodeIdx;
                 }
                 node->NextLevel = nextIdx;
@@ -145,12 +159,12 @@ namespace Nitload.Common.HighPerformance.Memory
                     _bucket[currentLevel] = currentNextLevelIdx;
                 } else if (currentPrevLevelIdx != 0)
                 {
-                    CacheLineMetadata* prevLevel = &_spareMemory[currentPrevLevelIdx];
+                    CacheLineMetadata* prevLevel = MetadataAt(currentPrevLevelIdx);
                     prevLevel->NextLevel = currentNextLevelIdx;
                 }
                 if (currentNextLevelIdx != 0)
                 {
-                    CacheLineMetadata* nextLevel = &_spareMemory[currentNextLevelIdx];
+                    CacheLineMetadata* nextLevel = MetadataAt(currentNextLevelIdx);
                     nextLevel->PreviousLevel = currentPrevLevelIdx;
                 }
                 node->PreviousLevel = 0;
@@ -203,11 +217,11 @@ namespace Nitload.Common.HighPerformance.Memory
                         meta = null;
                         return false;
                     }
-                    meta = &_spareMemory[idx];
+                    meta = MetadataAt(idx);
                     short nextSpareIdx = meta->NextLevel;
                     if (nextSpareIdx != 0)
                     {
-                        CacheLineMetadata* nextSpare = &_spareMemory[nextSpareIdx];
+                        CacheLineMetadata* nextSpare = MetadataAt(nextSpareIdx);
                         nextSpare->PreviousLevel = 0;
                     }
                     _spareMemory->NextLevel = nextSpareIdx;
@@ -215,18 +229,19 @@ namespace Nitload.Common.HighPerformance.Memory
                 if (!TryGetNewMetadata(out meta)) {
                     return false;
                 }
+                idx = (short)(_spareMemory - meta);
                 spareSize -= size;
                 meta->SizeMask = size;
-                meta->PositionMask = _spareMemory->PositionMask;
+                meta->Position = _spareMemory->Position;
                 meta->State = AllocationState.Free;
                 meta->PreviousLevel = 0;
                 meta->NextLevel = 0;
                 _spareMemory->SizeMask = spareSize;
-                _spareMemory->PositionMask += size;
+                _spareMemory->Position += size;
 
                 // insert the new chunk to position chain
                 short nearIdx = _spareMemory->PreviousNear;
-                CacheLineMetadata* near = &_spareMemory[nearIdx];
+                CacheLineMetadata* near = MetadataAt(nearIdx);
                 near->NextNear = idx;
                 meta->PreviousNear = nearIdx;
                 _spareMemory->PreviousNear = idx;
@@ -245,7 +260,7 @@ namespace Nitload.Common.HighPerformance.Memory
                     return false;
                 }
                 _metadataEnd++;
-                meta = &_spareMemory[_metadataEnd];
+                meta = MetadataAt(_metadataEnd);
                 return true;
             }
 
@@ -261,7 +276,7 @@ namespace Nitload.Common.HighPerformance.Memory
                     int idx = _bucket[level];
                     while (idx != 0)
                     {
-                        CacheLineMetadata* candidate = &_spareMemory[idx];
+                        CacheLineMetadata* candidate = MetadataAt(idx);
                         if (candidate->SizeMask >= minimumSize)
                         {
                             RemoveFromBucket(level, candidate, idx);
@@ -276,7 +291,7 @@ namespace Nitload.Common.HighPerformance.Memory
                     int idx = _bucket[i];
                     if (idx != 0)
                     {
-                        CacheLineMetadata* candidate = &_spareMemory[idx];
+                        CacheLineMetadata* candidate = MetadataAt(idx);
                         RemoveFromBucketHead(i, candidate, idx);
                         entry = candidate;
                         return true;
@@ -313,7 +328,7 @@ namespace Nitload.Common.HighPerformance.Memory
                     TryGetNewMetadata(out CacheLineMetadata* newEntry))
                 {
                     short newEntryIdx = (short)(_spareMemory - newEntry);
-                    newEntry->PositionMask = entry->PositionMask + allocSize;
+                    newEntry->Position = entry->Position + allocSize;
                     newEntry->SizeMask = remain;
                     newEntry->State = AllocationState.Free;
                     int newLevel = GetLevel(remain);
@@ -321,7 +336,7 @@ namespace Nitload.Common.HighPerformance.Memory
                     if (bucketHeadIdx != 0)
                     {
                         // if there is already an entry in the bucket, link it to the new entry
-                        CacheLineMetadata* bucketHead = &_spareMemory[bucketHeadIdx];
+                        CacheLineMetadata* bucketHead = MetadataAt(bucketHeadIdx);
                         bucketHead->PreviousLevel = newEntryIdx;
                     }
                     newEntry->NextLevel = bucketHeadIdx;
@@ -331,14 +346,14 @@ namespace Nitload.Common.HighPerformance.Memory
 
                     // push to position chain
                     short afterIdx = entry->NextNear;
-                    CacheLineMetadata* after = &_spareMemory[afterIdx];
+                    CacheLineMetadata* after = MetadataAt(afterIdx);
                     newEntry->NextNear = afterIdx;
                     after->PreviousNear = newEntryIdx;
                     entry->NextNear = newEntryIdx;
                     newEntry->PreviousNear = entryIdx;
                 }
                 entry->State = AllocationState.Alloc;
-                if (entry->PositionMask - (ulong)_basePtr > _totalSize) {
+                if (entry->Position - (ulong)_basePtr > _totalSize) {
                     throw new OverflowException("Allocated memory address exceeds the maximum block size.");
                 }
                 return entryIdx;
@@ -353,7 +368,7 @@ namespace Nitload.Common.HighPerformance.Memory
                     {
                         break;
                     }
-                    CacheLineMetadata* current = &_spareMemory[currentIdx];
+                    CacheLineMetadata* current = MetadataAt(currentIdx);
                     if (current->State == AllocationState.Free)
                     {
                         // scan next
@@ -361,7 +376,7 @@ namespace Nitload.Common.HighPerformance.Memory
                         int nextIdx = current->NextNear;
                         while (nextIdx != 0)
                         {
-                            CacheLineMetadata* next = &_spareMemory[nextIdx];
+                            CacheLineMetadata* next = MetadataAt(nextIdx);
                             if (next->State != AllocationState.Free)
                             {
                                 break;
@@ -378,7 +393,7 @@ namespace Nitload.Common.HighPerformance.Memory
                             short bucketHeadIdx = _bucket[newLevel];
                             if (bucketHeadIdx != 0)
                             {
-                                CacheLineMetadata* bucketHead = &_spareMemory[bucketHeadIdx];
+                                CacheLineMetadata* bucketHead = MetadataAt(bucketHeadIdx);
                                 bucketHead->PreviousLevel = currentIdx;
                             }
                             current->NextLevel = bucketHeadIdx;
@@ -391,11 +406,13 @@ namespace Nitload.Common.HighPerformance.Memory
             }
 
             public void Free(
-                        int handle,
+                        CacheLineMetadata* head,
                         int collectScanWindow = 4
             )
             {
-                CacheLineMetadata* head = &_spareMemory[handle];
+                if (head < _spareMemory || head >= _spareMemory + MaxCacheLineCount) {
+                    throw new ArgumentOutOfRangeException(nameof(head), "Handle is out of range.");
+                }
                 short headIdx = (short)(_spareMemory - head);
                 uint size = head->SizeMask;
                 for (int i = 0; i < collectScanWindow; i++)
@@ -406,13 +423,13 @@ namespace Nitload.Common.HighPerformance.Memory
                     {
                         break;
                     }
-                    CacheLineMetadata* prev = &_spareMemory[forwardIdx];
+                    CacheLineMetadata* prev = MetadataAt(forwardIdx);
                     if (prev->State != AllocationState.Free)
                     {
                         break;
                     }
                     size += prev->SizeMask;
-                    head->PositionMask = prev->PositionMask;
+                    head->Position = prev->Position;
                     RecycleNode(prev);
                 }
                 for (int i = 0; i < collectScanWindow; i++)
@@ -423,7 +440,7 @@ namespace Nitload.Common.HighPerformance.Memory
                     {
                         break;
                     }
-                    CacheLineMetadata* prev = &_spareMemory[nextIdx];
+                    CacheLineMetadata* prev = MetadataAt(nextIdx);
                     if (prev->State != AllocationState.Free)
                     {
                         break;
@@ -441,7 +458,7 @@ namespace Nitload.Common.HighPerformance.Memory
                 head->NextLevel = 0;
                 if (bucketHeadIdx != 0)
                 {
-                    CacheLineMetadata* bucketHead = &_spareMemory[bucketHeadIdx];
+                    CacheLineMetadata* bucketHead = MetadataAt(bucketHeadIdx);
                     bucketHead->PreviousLevel = headIdx;
                     head->NextLevel = bucketHeadIdx;
                 }
@@ -449,6 +466,27 @@ namespace Nitload.Common.HighPerformance.Memory
                 return;
             }
 
+            public void Free(
+                        ulong handle,
+                        int collectScanWindow = 4
+            )
+            {
+                if (handle < (ulong)_basePtr || handle >= (ulong)_basePtr + _totalSize) {
+                    throw new ArgumentOutOfRangeException(nameof(handle), "Handle is out of range.");
+                }
+                CacheLineMetadata* head = (CacheLineMetadata*)handle;
+                Free(head, collectScanWindow);
+            }
+
+            public void Free(
+                        int handle,
+                        int collectScanWindow = 4
+            )
+            {
+                CacheLineMetadata* head = MetadataAt(handle);
+                Free(head, collectScanWindow);
+            }
+
             public bool TryAlloc(
                         uint size,
                         out int h
@@ -479,7 +517,7 @@ namespace Nitload.Common.HighPerformance.Memory
                 if (remain > (entrySize >> 7) && TryGetNewMetadata(out CacheLineMetadata* newEntry))
                 {
                     short newEntryIdx = (short)(_spareMemory - newEntry);
-                    newEntry->PositionMask = entry->PositionMask + allocSize;
+                    newEntry->Position = entry->Position + allocSize;
                     newEntry->SizeMask = remain;
                     newEntry->State = AllocationState.Free;
                     int newLevel = GetLevel(remain);
@@ -487,7 +525,7 @@ namespace Nitload.Common.HighPerformance.Memory
                     if (bucketHeadIdx != 0)
                     {
                         // if there is already an entry in the bucket, link it to the new entry
-                        CacheLineMetadata* bucketHead = &_spareMemory[bucketHeadIdx];
+                        CacheLineMetadata* bucketHead = MetadataAt(bucketHeadIdx);
                         newEntry->NextLevel = bucketHeadIdx;
                         bucketHead->PreviousLevel = newEntryIdx;
                     } else
@@ -499,14 +537,14 @@ namespace Nitload.Common.HighPerformance.Memory
 
                     // push to position chain
                     short afterIdx = entry->NextNear;
-                    CacheLineMetadata* after = &_spareMemory[afterIdx];
+                    CacheLineMetadata* after = MetadataAt(afterIdx);
                     newEntry->NextNear = afterIdx;
                     after->PreviousNear = newEntryIdx;
                     entry->NextNear = newEntryIdx;
                     newEntry->PreviousNear = entryIdx;
                 }
                 entry->State = AllocationState.Alloc;
-                if (entry->PositionMask - (ulong)_basePtr > _totalSize)
+                if (entry->Position - (ulong)_basePtr > _totalSize)
                 {
                     h = default;
                     throw new OverflowException("Allocated memory address exceeds the maximum block size.");

src/Nitload.Common/HighPerformance/Memory/L4.cs

@@ -12,7 +12,12 @@ namespace Nitload.Common.HighPerformance.Memory
     public sealed unsafe partial class L4 : IDisposable
     {
 
+        private const int MaxActiveCacheLineCount = 8192;
+
         private const nuint PageSize = 4096;
+        private const int PredictorRingCapacity = 256;
+
+        private readonly IL4Predictor[] _ring;
 
         private bool _disposed;
         private readonly int _bindedNuma;
@@ -29,6 +34,7 @@ namespace Nitload.Common.HighPerformance.Memory
         {
             ArgumentOutOfRangeException.ThrowIfGreaterThan(bufferSize, CacheLineMetadata.MaxBufferSize);
             ArgumentOutOfRangeException.ThrowIfGreaterThan(maxCacheLineSize, CacheLineMetadata.MaxBufferSize);
+            _ring = new IL4Predictor[PredictorRingCapacity];
             _bindedNuma = bindedNuma;
             _predict_slow_path_count = GetPredictSlowPathCount(bindedNuma);
             nuint normalizedBufferSize = (bufferSize + (PageSize - 1)) & (~(PageSize - 1));
@@ -73,6 +79,8 @@ namespace Nitload.Common.HighPerformance.Memory
             _bufferAllocator.Free(handle);
         }
 
+        internal partial int Predict();
+
         internal bool TryAllocate(
                       uint size,
                       out int handle
@@ -82,15 +90,16 @@ namespace Nitload.Common.HighPerformance.Memory
             return _bufferAllocator.TryAlloc(size, out handle);
         }
 
-        internal partial int Predict();
+        private static int GetPredictSlowPathCount(
-
+                           int bindedNuma
-        private static int GetPredictSlowPathCount(int bindedNuma)
+        )
         {
             foreach (NumaNode node in Numa.AllNumaNode)
             {
-                if (node.NumaNodeId == (uint)bindedNuma)
+                if (node.NumaNodeId == (uint)bindedNuma) {
                     return checked(node.LogicalCoreCount * 2);
                 }
+            }
 
             throw new ArgumentOutOfRangeException(nameof(bindedNuma), "No topology information exists for the bound NUMA node.");
         }

src/Nitload.Common/HighPerformance/Memory/L4Predictor.cs

@@ -22,6 +22,12 @@ namespace Nitload.Common.HighPerformance.Memory
             in Span<L4.AddressSource> RequiredBuffer
         );
 
+        void Prefetch(
+             L4.AddressSource RequiredBuffer,
+             nuint allocBuffer,
+             nuint bufferSize
+        );
+
     }
 
     public interface IL4Predictor<TMission> : IL4Predictor
@@ -32,5 +38,4 @@ namespace Nitload.Common.HighPerformance.Memory
         );
 
     }
-
 }