improve Types

LoneWandererProductions · LoneWandererProductions · commit ad8187cfdb4f · 2026-06-09T08:27:34.000+02:00
diff --git a/MemoryManager.Types/ArenaList.cs b/MemoryManager.Types/ArenaList.cs
@@ -2,7 +2,7 @@
  * COPYRIGHT:   See COPYING in the top level directory
  * PROJECT:     MemoryManager.Types
  * FILE:        ArenaList.cs
- * PURPOSE:     A resizable, unmanaged list backed by a MemoryArena. 
+ * PURPOSE:     A resizable, unmanaged list backed by an IMemoryAllocator interface contract. 
  *              Automatically handles growth and memory reclamation via handles.
  * PROGRAMMER:  Peter Geinitz (Wayfarer)
  */
@@ -14,15 +14,15 @@ namespace MemoryManager.Types
 {
     /// <summary>
     /// A high-performance, resizable list for unmanaged types that allocates
-    /// its internal buffer from a <see cref="MemoryArena"/>.
+    /// its internal buffer from an <see cref="IMemoryAllocator"/>.
     /// </summary>
     /// <typeparam name="T">The unmanaged type to store.</typeparam>
     public sealed class ArenaList<T> : IDisposable where T : unmanaged
     {
         /// <summary>
         /// The arena
         /// </summary>
-        private readonly MemoryArena _arena;
+        private readonly IMemoryAllocator _arena;
 
         /// <summary>
         /// The priority
@@ -55,10 +55,18 @@ public sealed class ArenaList<T> : IDisposable where T : unmanaged
         public int Capacity => _capacity;
 
         /// <summary>
-        /// Initializes a new instance of the <see cref="ArenaList{T}"/> class.
+        /// Initializes a new instance of the <see cref="ArenaList{T}" /> class.
         /// </summary>
+<<<<<<< HEAD
+        /// <param name="arena">The arena.</param>
+        /// <param name="initialCapacity">The initial capacity.</param>
+        /// <param name="priority">The priority.</param>
+        /// <param name="hints">The hints.</param>
+        public ArenaList(IMemoryAllocator arena, int initialCapacity = 8, AllocationPriority priority = AllocationPriority.Normal, AllocationHints hints = AllocationHints.None)
+=======
         public ArenaList(MemoryArena arena, int initialCapacity = 8,
             AllocationPriority priority = AllocationPriority.Normal, AllocationHints hints = AllocationHints.None)
+>>>>>>> f41cf23e1c66b3d2e4e393356f32f92443e0ab03
         {
             if (initialCapacity <= 0) initialCapacity = 8;
 
@@ -67,56 +75,60 @@ public ArenaList(MemoryArena arena, int initialCapacity = 8,
             _priority = priority;
             _hints = hints;
 
-            // Allocate the initial contiguous block from the arena using explicit design parameters
             _handle = _arena.Allocate(Unsafe.SizeOf<T>() * _capacity, _priority, _hints);
         }
 
         /// <summary>
-        /// Gets or sets the element at the specified index via direct address reference tracking expressions.
+        /// Gets the <see cref="T"/> at the specified index.
         /// </summary>
-        /// <remarks>
-        /// Warning: Avoid using this indexer heavily inside tight loops, as each invocation incurs a synchronization check.
-        /// For performance-critical iteration paths, extract a transient block layout using <see cref="AsSpan"/> instead.
-        /// </remarks>
+        /// <value>
+        /// The <see cref="T"/>.
+        /// </value>
+        /// <param name="index">The index.</param>
+        /// <returns></returns>
         public ref T this[int index] => ref Get(index);
 
         /// <summary>
-        /// Adds an item to the list, automatically growing the internal buffer if necessary.
+        /// Adds the specified item.
         /// </summary>
+        /// <param name="item">The item.</param>
         public void Add(T item)
         {
             if (Count == _capacity) Grow();
 
-            // Resolve layout constraints safely and insert item at tracking high-water marks
             var span = _arena.GetSpan<T>(_handle, _capacity);
             span[Count++] = item;
         }
 
         /// <summary>
-        /// Returns a reference to the element at the specified index.
+        /// Gets the specified index.
         /// </summary>
+        /// <param name="index">The index.</param>
+        /// <returns></returns>
+        /// <exception cref="System.IndexOutOfRangeException">Index {index} is outside active boundaries.</exception>
         public ref T Get(int index)
         {
             if (index < 0 || index >= Count)
+<<<<<<< HEAD
+                throw new IndexOutOfRangeException($"Index {index} is outside active boundaries.");
+=======
                 throw new IndexOutOfRangeException(
                     $"Index {index} is outside the active boundaries of the ArenaList (Count: {Count}).");
+>>>>>>> f41cf23e1c66b3d2e4e393356f32f92443e0ab03
 
             var span = _arena.GetSpan<T>(_handle, _capacity);
             return ref span[index];
         }
 
         /// <summary>
-        /// Resets the count to zero. Note: Does not clear memory tracking until an arena cycle triggers maintenance.
+        /// Clears this instance.
         /// </summary>
-        public void Clear()
-        {
-            Count = 0;
-        }
+        public void Clear() => Count = 0;
 
         /// <summary>
-        /// Exposes a fast, direct raw hardware <see cref="Span{T}"/> over the active items list.
-        /// This completely bypasses inner index loops lock overhead constraints.
+        /// Ases the span.
         /// </summary>
+        /// <returns></returns>
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
         public Span<T> AsSpan()
         {
@@ -125,29 +137,33 @@ public Span<T> AsSpan()
         }
 
         /// <summary>
-        /// Doubles the capacity of the list by allocating a new handle and migrating data.
+        /// Exposes a zero-allocation, struct-based enumerator.
+        /// Allows clean 'foreach' loop compilation bypassing the managed Garbage Collector entirely.
+        /// </summary>
+        /// <returns>An enumerator for the list.</returns>
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public Span<T>.Enumerator GetEnumerator() => AsSpan().GetEnumerator();
+
+        /// <summary>
+        /// Grows this instance.
         /// </summary>
         private void Grow()
         {
             var newCapacity = _capacity * 2;
             var newHandle = _arena.Allocate(Unsafe.SizeOf<T>() * newCapacity, _priority, _hints);
 
-            // Fetch structural views over original and destination arrays atomically
             var oldSpan = _arena.GetSpan<T>(_handle, _capacity);
             var newSpan = _arena.GetSpan<T>(newHandle, newCapacity);
 
-            // Execute blazing fast bitwise memory migration copy operations
             oldSpan.CopyTo(newSpan);
-
-            // Reclaim legacy positions within the parent lane array trackers instantly
             _arena.Free(_handle);
 
             _handle = newHandle;
             _capacity = newCapacity;
         }
 
         /// <summary>
-        /// Releases the unmanaged memory handle pool block back to the parent arena coordinator framework.
+        /// Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.
         /// </summary>
         public void Dispose()
         {
diff --git a/MemoryManager.Types/ArenaQueue.cs b/MemoryManager.Types/ArenaQueue.cs
@@ -0,0 +1,206 @@
+﻿/*
+ * COPYRIGHT:   See COPYING in the top level directory
+ * PROJECT:     MemoryManager.Types
+ * FILE:        ArenaQueue.cs
+ * PURPOSE:     A high-performance, resizable unmanaged Ring Buffer (Circular Queue).
+ *              Manages wrap-around index alignment and unmanaged data unwrapping.
+ * PROGRAMMER:  Peter Geinitz (Wayfarer)
+ */
+
+using MemoryManager.Core;
+using System.Runtime.CompilerServices;
+
+namespace MemoryManager.Types
+{
+    /// <summary>
+    /// A high-performance, zero-allocation circular queue (Ring Buffer) for unmanaged types,
+    /// backed by an <see cref="IMemoryAllocator"/>.
+    /// </summary>
+    /// <typeparam name="T">The unmanaged type to store.</typeparam>
+    public sealed class ArenaQueue<T> : IDisposable where T : unmanaged
+    {
+        /// <summary>
+        /// The arena
+        /// </summary>
+        private readonly IMemoryAllocator _arena;
+
+        /// <summary>
+        /// The priority
+        /// </summary>
+        private readonly AllocationPriority _priority;
+
+        /// <summary>
+        /// The hints
+        /// </summary>
+        private readonly AllocationHints _hints;
+
+        /// <summary>
+        /// The handle
+        /// </summary>
+        private MemoryHandle _handle;
+
+        /// <summary>
+        /// The capacity
+        /// </summary>
+        private int _capacity;
+
+        /// <summary>
+        /// The head
+        /// </summary>
+        private int _head;
+
+        /// <summary>
+        /// The tail
+        /// </summary>
+        private int _tail;
+
+        /// <summary>
+        /// The count
+        /// </summary>
+        private int _count;
+
+        /// <summary>
+        /// Gets the number of elements currently waiting in the queue.
+        /// </summary>
+        public int Count => _count;
+
+        /// <summary>
+        /// Gets the total size of the internal native ring loop before a resize triggers.
+        /// </summary>
+        public int Capacity => _capacity;
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="ArenaQueue{T}" /> class.
+        /// </summary>
+        /// <param name="arena">The arena.</param>
+        /// <param name="initialCapacity">The initial capacity.</param>
+        /// <param name="priority">The priority.</param>
+        /// <param name="hints">The hints.</param>
+        public ArenaQueue(IMemoryAllocator arena, int initialCapacity = 8, AllocationPriority priority = AllocationPriority.Normal, AllocationHints hints = AllocationHints.None)
+        {
+            if (initialCapacity <= 0) initialCapacity = 8;
+
+            _arena = arena;
+            _capacity = initialCapacity;
+            _priority = priority;
+            _hints = hints;
+
+            // Allocate the circular block segment tracking structural alignment properties
+            _handle = _arena.Allocate(Unsafe.SizeOf<T>() * _capacity, _priority, _hints);
+            _head = 0;
+            _tail = 0;
+            _count = 0;
+        }
+
+        /// <summary>
+        /// Pushes an item to the back of the circular queue, automatically growing the array if full.
+        /// </summary>
+        /// <param name="item">The item.</param>
+        public void Enqueue(T item)
+        {
+            if (_count == _capacity) Grow();
+
+            var span = _arena.GetSpan<T>(_handle, _capacity);
+            span[_tail] = item;
+
+            // The Clockwork Magic: Wrap index back around to 0 if it overshoots the hardware boundary
+            _tail = (_tail + 1) % _capacity;
+            _count++;
+        }
+
+        /// <summary>
+        /// Pops and returns the oldest item from the front of the circular queue.
+        /// </summary>
+        /// <returns></returns>
+        /// <exception cref="System.InvalidOperationException">The ArenaQueue is empty.</exception>
+        public T Dequeue()
+        {
+            if (_count == 0)
+                throw new InvalidOperationException("The ArenaQueue is empty.");
+
+            var span = _arena.GetSpan<T>(_handle, _capacity);
+            T item = span[_head];
+
+            // Advance the front coordinate tracking pointer around the ring loop
+            _head = (_head + 1) % _capacity;
+            _count--;
+
+            return item;
+        }
+
+        /// <summary>
+        /// Evaluates the front-most item without popping it from the data lane buffer.
+        /// </summary>
+        /// <returns></returns>
+        /// <exception cref="System.InvalidOperationException">The ArenaQueue is empty.</exception>
+        public ref T Peek()
+        {
+            if (_count == 0)
+                throw new InvalidOperationException("The ArenaQueue is empty.");
+
+            var span = _arena.GetSpan<T>(_handle, _capacity);
+            return ref span[_head];
+        }
+
+        /// <summary>
+        /// Resets structural coordinates to zero. Memory retains previous properties until reclamation sweeps.
+        /// </summary>
+        public void Clear()
+        {
+            _head = 0;
+            _tail = 0;
+            _count = 0;
+        }
+
+        /// <summary>
+        /// The Unwrapping Engine: Allocates a double-sized ring loop and cleanly flattens
+        /// segmented wrap-around data fragments into a unified linear coordinate system.
+        /// </summary>
+        private void Grow()
+        {
+            var newCapacity = _capacity * 2;
+            var newHandle = _arena.Allocate(Unsafe.SizeOf<T>() * newCapacity, _priority, _hints);
+
+            var oldSpan = _arena.GetSpan<T>(_handle, _capacity);
+            var newSpan = _arena.GetSpan<T>(newHandle, newCapacity);
+
+            if (_count > 0)
+            {
+                // Case 1: Contiguous layout block (Head is positioned behind Tail)
+                if (_head < _tail)
+                {
+                    oldSpan.Slice(_head, _count).CopyTo(newSpan);
+                }
+                // Case 2: Fractured layout block (Tail wrapped around and is positioned ahead of Head)
+                else
+                {
+                    // Step A: Copy from Head to the physical end of the old unmanaged buffer array block
+                    var headSegmentSize = _capacity - _head;
+                    oldSpan.Slice(_head, headSegmentSize).CopyTo(newSpan);
+
+                    // Step B: Copy remaining wrapped trailing elements from index 0 up to the Tail marker position
+                    oldSpan.Slice(0, _tail).CopyTo(newSpan.Slice(headSegmentSize));
+                }
+            }
+
+            // Recycle old positions and update spatial properties
+            _arena.Free(_handle);
+            _handle = newHandle;
+            _head = 0;
+            _tail = _count; // Tail is now cleanly positioned right after our linear block data cluster
+            _capacity = newCapacity;
+        }
+
+        /// <summary>
+        /// Cleans up unmanaged boundaries back to native runtime engines safely.
+        /// </summary>
+        public void Dispose()
+        {
+            if (!_handle.IsInvalid)
+            {
+                _arena.Free(_handle);
+                _handle = default;
+            }
+        }
+    }
+}
diff --git a/MemoryManager/MemoryArenaExtensions.cs b/MemoryManager/MemoryArenaExtensions.cs
@@ -131,5 +131,26 @@ public static void BulkSet<T>(this IMemoryAllocator arena, MemoryHandle handle,
             // Bypasses instance type inference by passing T explicitly
             arena.BulkSet<T>(handle, source);
         }
+
+        /// <summary>
+        /// Resolves a memory handle and creates a direct, high-performance <see cref="Span{T}"/> view over the native memory block.
+        /// </summary>
+        /// <typeparam name="T">The unmanaged value type.</typeparam>
+        /// <param name="allocator">The allocation engine.</param>
+        /// <param name="handle">The tracking handle tracking the allocation site.</param>
+        /// <param name="count">The number of elements of type T to include in the span view.</param>
+        /// <returns>A span tracking the underlying raw native block coordinates.</returns>
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public static unsafe Span<T> GetSpan<T>(this IMemoryAllocator allocator, MemoryHandle handle, int count) where T : unmanaged
+        {
+            if (handle.IsInvalid || count <= 0) return Span<T>.Empty;
+
+            // Resolve handles thread-isolation tracks or global locks automatically
+            nint pointer = allocator.Resolve(handle);
+            if (pointer == nint.Zero) return Span<T>.Empty;
+
+            // Pivot straight into raw unmanaged address spaces
+            return new Span<T>((void*)pointer, count);
+        }
     }
 }
