Enhance memory management and data structures

Updated `CollectionBenchmark` for setup/cleanup methods,
streamlined benchmarking in `Program.cs`, and improved
documentation in `AllocationOption` and `Allocator` enums.
Made `Enumerator` structs public in several collections
and clarified constructor parameters. Introduced a new
`UnsafeStack` struct for stack operations. Enhanced
`AllocationManager` with better memory tracking and
management, ensuring proper allocation and disposal.

Misaki.HighPerformance.Test/CollectionBenchmark.cs

@@ -10,32 +10,28 @@ public class CollectionBenchmark
     [Params(10, 100, 1000)]
     public int count = 100;
 
+    [GlobalSetup]
+    public void Setup()
+    {
+        AllocationManager.Initialize(512_000);
+    }
+
     [Benchmark]
     public void Array()
-    {
-        for (var i = 0; i < count; i++)
     {
         var array = new int[count];
     }
-    }
 
     [Benchmark]
     public void UnsafeArray()
-    {
-        for (var i = 0; i < count; i++)
     {
         var array = new UnsafeArray<int>(count, Allocator.Temp);
-            for (var j = 0; j < count; j++)
-            {
-                array[j] = j;
-            }
-
-            foreach (var item in array)
-            {
-                Console.WriteLine(item);
-            }
-
         AllocationManager.Reset();
     }
+
+    [GlobalCleanup]
+    public void Cleanup()
+    {
+        AllocationManager.Dispose();
     }
 }

Misaki.HighPerformance.Test/Program.cs

@@ -1,7 +1,4 @@
-using Misaki.HighPerformance.Test;
+using BenchmarkDotNet.Running;
-using Misaki.HighPerformance.Unsafe.Services;
+using Misaki.HighPerformance.Test;
 
-AllocationManager.Initialize(512_000);
+BenchmarkRunner.Run<CollectionBenchmark>();
-var test = new CollectionBenchmark();
-test.UnsafeArray();
-AllocationManager.Dispose();

Misaki.HighPerformance.Unsafe/Collections/AllocationOption.cs

@@ -2,14 +2,32 @@
 
 public enum AllocationOption : byte
 {
+    /// <summary>
+    /// Allocator for uninitialized memory
+    /// </summary>
     UnInitialized,
-    Clear
+    /// <summary>
+    /// Allocator for initialized memory.
+    /// </summary>
+    Clear,
+    /// <summary>
+    /// Allocator for untracked memory.
+    /// Use this option carefully, as the allocation manager will not track the memory.
+    /// No warning will be given if the memory is not freed.
+    /// </summary>
+    UnTracked
 }
 
 public enum Allocator : byte
 {
     // Make the first allocator as invalid because we don't want to user create a defualt collection without passing any parameters
-    Invalid = 0,
+    Invalid,
-    Temp = 1,
+    /// <summary>
-    Persistent = 2,
+    /// Allocator for temporary allocations. Allocations are cleared after use.
+    /// </summary>
+    Temp,
+    /// <summary>
+    /// Allocator for persistent allocations. Allocations are not cleared after use.
+    /// </summary>
+    Persistent,
 }

Misaki.HighPerformance.Unsafe/Collections/UnsafeArray.cs

@@ -13,7 +13,7 @@ namespace Misaki.HighPerformance.Unsafe.Collections;
 public unsafe struct UnsafeArray<T> : IUnsafeCollection<T>
     where T : unmanaged
 {
-    private struct Enumerator : IEnumerator<T>
+    public struct Enumerator : IEnumerator<T>
     {
         private UnsafeArray<T>* _collection;
         private int _index;
@@ -90,30 +90,30 @@ public unsafe struct UnsafeArray<T> : IUnsafeCollection<T>
     /// allocates memory and optionally clears it.
     /// </summary>
     /// <param name="count">Specifies the number of elements to allocate in the array, which must be greater than zero.</param>
-    /// <param name="allocationType">Determines how the allocated memory should be initialized, either uninitialized or cleared.</param>
+    /// <param name="allocator">Specifies the allocator to use for memory allocation, which determines the memory management strategy.</param>
+    /// <param name="allocationOption">Determines how the allocated memory should be initialized, either uninitialized or cleared.</param>
     /// <exception cref="ArgumentOutOfRangeException">Thrown when the specified number of elements is less than or equal to zero.</exception>
-    public UnsafeArray(int count, Allocator allocator, AllocationOption allocationType = AllocationOption.UnInitialized)
+    public UnsafeArray(int count, Allocator allocator, AllocationOption allocationOption = AllocationOption.UnInitialized)
     {
         if (count <= 0)
         {
             throw new ArgumentOutOfRangeException(nameof(count), "Count must be greater than zero.");
         }
 
-        _buffer = AllocationManager.Allocate<T>((uint)count, (uint)AlignOf<T>(), allocator, allocationType);
+        _buffer = AllocationManager.Allocate<T>((uint)count, (uint)AlignOf<T>(), allocator, allocationOption);
         _count = count;
 
-        if (allocationType == AllocationOption.Clear)
+        if (allocationOption == AllocationOption.Clear)
         {
             Clear();
         }
     }
 
     /// <summary>
-    /// Initializes an UnsafeArray with a pointer to a buffer and a count of elements. The count is adjusted based on
+    /// Initializes an UnsafeArray with a pointer to a buffer and a count of elements.
-    /// the size of the type T.
     /// </summary>
     /// <param name="buffer">A pointer to the memory location that holds the elements of the array.</param>
-    /// <param name="count">The total size of the data in bytes, which is divided by the size of type T to determine the number of elements.</param>
+    /// <param name="count">The total size of the data.</param>
     public UnsafeArray(void* buffer, int count)
     {
         _buffer = (T*)buffer;

Misaki.HighPerformance.Unsafe/Collections/UnsafeHashMap.cs

@@ -7,7 +7,7 @@ namespace Misaki.HighPerformance.Unsafe.Collections;
 
 public unsafe struct UnsafeHashMap<TKey, TValue> : IUnsafeCollection<KeyValuePair<TKey, TValue>> where TKey : unmanaged, IEquatable<TKey> where TValue : unmanaged
 {
-    private struct Enumerator : IEnumerator<KeyValuePair<TKey, TValue>>
+    public struct Enumerator : IEnumerator<KeyValuePair<TKey, TValue>>
     {
         internal HashMapHelper<TKey>.Enumerator _enumerator;
 

Misaki.HighPerformance.Unsafe/Collections/UnsafeHashSet.cs

@@ -13,7 +13,7 @@ namespace Misaki.HighPerformance.Unsafe.Collections;
 public unsafe struct UnsafeHashSet<T> : IUnsafeCollection<T>, IEnumerable<T>
     where T : unmanaged, IEquatable<T>
 {
-    private struct Enumerator : IEnumerator<T>
+    public struct Enumerator : IEnumerator<T>
     {
         internal HashMapHelper<T>.Enumerator _enumerator;
 

Misaki.HighPerformance.Unsafe/Collections/UnsafeList.cs

@@ -12,7 +12,7 @@ namespace Misaki.HighPerformance.Unsafe.Collections;
 public unsafe struct UnsafeList<T> : IUnsafeCollection<T>
     where T : unmanaged
 {
-    private struct Enumerator : IEnumerator<T>
+    public struct Enumerator : IEnumerator<T>
     {
         private UnsafeList<T>* _collection;
         private int _index;
@@ -132,12 +132,6 @@ public unsafe struct UnsafeList<T> : IUnsafeCollection<T>
     public UnsafeList(int capacity, Allocator allocator, AllocationOption allocationType = AllocationOption.UnInitialized)
     {
         _array = new UnsafeArray<T>(capacity, allocator, allocationType);
-        _count = 0;
-
-        if (allocationType == AllocationOption.Clear)
-        {
-            Clear();
-        }
     }
 
     private readonly void CheckNoResizeCapacity(int count)

Misaki.HighPerformance.Unsafe/Collections/UnsafeQueue.cs

@@ -13,7 +13,7 @@ namespace Misaki.HighPerformance.Unsafe.Collections;
 public unsafe struct UnsafeQueue<T> : IUnsafeCollection<T>
     where T : unmanaged
 {
-    private struct Enumerator : IEnumerator<T>
+    public struct Enumerator : IEnumerator<T>
     {
         private UnsafeQueue<T>* _collection;
         private int _index;
@@ -83,13 +83,6 @@ public unsafe struct UnsafeQueue<T> : IUnsafeCollection<T>
     public UnsafeQueue(int capacity, Allocator allocator, AllocationOption allocationType = AllocationOption.UnInitialized)
     {
         _array = new UnsafeArray<T>(capacity, allocator, allocationType);
-        _count = 0;
-        _offset = 0;
-
-        if (allocationType == AllocationOption.Clear)
-        {
-            Clear();
-        }
     }
 
     /// <summary>
@@ -132,7 +125,7 @@ public unsafe struct UnsafeQueue<T> : IUnsafeCollection<T>
     /// </summary>
     /// <param name="value">The output variable that will hold the dequeued item if the operation is successful.</param>
     /// <returns>True if an item was successfully dequeued, otherwise false.</returns>
-    public bool TryDequeue([MaybeNullWhen(false)] out T value)
+    public bool TryDequeue(out T value)
     {
         if (_count == 0)
         {

Misaki.HighPerformance.Unsafe/Collections/UnsafeStack.cs

@@ -0,0 +1,104 @@
+using Misaki.HighPerformance.Unsafe.Collections.Contracts;
+using Misaki.HighPerformance.Unsafe.Helpers;
+using System.Collections;
+using System.Diagnostics.CodeAnalysis;
+using System.Runtime.CompilerServices;
+
+namespace Misaki.HighPerformance.Unsafe.Collections;
+
+public unsafe struct UnsafeStack<T> : IUnsafeCollection<T>
+    where T : unmanaged
+{
+    private UnsafeArray<T> _array;
+    private int _count;
+
+    public readonly int Count => _count;
+    public readonly bool IsCreated => _array.IsCreated;
+
+    public IEnumerator<T> GetEnumerator()
+    {
+        throw new NotImplementedException();
+    }
+    IEnumerator IEnumerable.GetEnumerator()
+    {
+        return GetEnumerator();
+    }
+
+    public UnsafeStack(int initialSize, Allocator allocator, AllocationOption allocationOption = AllocationOption.UnInitialized)
+    {
+        _array = new UnsafeArray<T>(initialSize, allocator, allocationOption);
+    }
+
+    public void Push(T value)
+    {
+        if (_count >= _array.Count)
+        {
+            Resize(_array.Count + (int)(_array.Count * 0.5f));
+        }
+
+        UnsafeUtilities.WriteArrayElement(_array.GetUnsafePtr(), _count, value);
+        _count++;
+    }
+
+    public T Pop()
+    {
+        if (_count == 0)
+        {
+            throw new InvalidOperationException("Stack is empty.");
+        }
+
+        _count--;
+        return _array[_count];
+    }
+
+    public bool TryPop(out T value)
+    {
+        if (_count == 0)
+        {
+            value = default;
+            return false;
+        }
+
+        _count--;
+        value = _array[_count];
+        return true;
+    }
+
+    public readonly T Peek()
+    {
+        if (_count == 0)
+        {
+            throw new InvalidOperationException("Stack is empty.");
+        }
+
+        return _array[_count - 1];
+    }
+
+    public void Resize(int newSize)
+    {
+        _array.Resize(newSize);
+
+        if (_count > newSize)
+        {
+            _count = newSize;
+        }
+    }
+
+    public void Clear()
+    {
+        _array.Clear();
+        _count = 0;
+    }
+
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public readonly void* GetUnsafePtr()
+    {
+        return _array.GetUnsafePtr();
+    }
+
+    public void Dispose()
+    {
+        _array.Dispose();
+        _count = 0;
+    }
+}

Misaki.HighPerformance.Unsafe/Services/AllocationManager.cs

@@ -1,47 +1,81 @@
 using Misaki.HighPerformance.Unsafe.Buffer;
 using Misaki.HighPerformance.Unsafe.Collections;
+using System.Runtime.CompilerServices;
 
 namespace Misaki.HighPerformance.Unsafe.Services;
 
 public static unsafe class AllocationManager
 {
+    private readonly struct AllocationInfo(void* ptr, nuint size)
+    {
+        public readonly void* ptr = ptr;
+        public readonly nuint size = size;
+    }
+
     private static DynamicArena _arena;
     private static bool _initialized;
 
+    private static UnsafeQueue<AllocationInfo> _allocated;
+
     private static readonly Lock _lock = new();
 
-    public static void Initialize(uint initialSize)
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
-    {
+    private static void VerifyInitialization()
-        _arena = new DynamicArena(initialSize);
-        _initialized = true;
-    }
-
-    internal static T* Allocate<T>(uint size, uint alignSize, Allocator allocator, AllocationOption allocationType)
-        where T : unmanaged
     {
         if (!_initialized)
         {
             throw new InvalidOperationException("The AllocationManager has not been initialized.");
         }
+    }
+
+    /// <summary>
+    /// Initializes the AllocationManager with a specified initial size for the memory arena.
+    /// </summary>
+    /// <param name="initialSize">The initial size in bytes for the memory arena.</param>
+    public static void Initialize(uint initialSize)
+    {
+        if (_initialized || initialSize <= 0)
+        {
+            return;
+        }
+
+        _arena = new DynamicArena(initialSize);
+        _allocated = new UnsafeQueue<AllocationInfo>(16, Allocator.Persistent);
+
+        _initialized = true;
+    }
+
+    internal static T* Allocate<T>(uint size, uint alignSize, Allocator allocator, AllocationOption allocationOption)
+        where T : unmanaged
+    {
+        if (allocationOption == AllocationOption.UnTracked)
+        {
+            return (T*)AlignedAlloc(size, alignSize);
+        }
+
+        VerifyInitialization();
 
         lock (_lock)
         {
-            return allocator switch
+            switch (allocator)
             {
-                Allocator.Temp => (T*)_arena.Allocate(size * (uint)sizeof(T), alignSize, allocationType),
+                case Allocator.Temp:
-                Allocator.Persistent => (T*)AlignedAlloc((nuint)(size * sizeof(T)), alignSize),
+                    return (T*)_arena.Allocate(size * (uint)sizeof(T), alignSize, allocationOption);
-                _ => throw new ArgumentOutOfRangeException(nameof(allocator), "Invalid allocator type."),
+
-            };
+                case Allocator.Persistent:
+                    var allocationSize = size * (nuint)sizeof(T);
+                    var buffer = (T*)AlignedAlloc(allocationSize, alignSize);
+                    _allocated.Enqueue(new AllocationInfo(buffer, allocationSize));
+                    return buffer;
+
+                default:
+                    throw new ArgumentOutOfRangeException(nameof(allocator), "Invalid allocator type.");
+            }
         }
     }
 
     internal static void Free(void* ptr, Allocator allocator)
     {
-        if (!_initialized)
-        {
-            throw new InvalidOperationException("The AllocationManager has not been initialized.");
-        }
-
         lock (_lock)
         {
             if (allocator == Allocator.Persistent)
@@ -51,18 +85,36 @@ public static unsafe class AllocationManager
         }
     }
 
+    /// <summary>
+    /// Resets the memory arena, optionally clearing the allocated memory.
+    /// </summary>
+    /// <param name="clear">If true, the allocated memory will be cleared; otherwise, it will not be cleared.</param>
     public static void Reset(bool clear = false)
     {
-        if (!_initialized)
+        VerifyInitialization();
-        {
-            throw new InvalidOperationException("The AllocationManager has not been initialized.");
-        }
-
         _arena.Reset(clear);
     }
 
+    /// <summary>
+    /// Disposes of the AllocationManager, freeing all allocated memory and resources.
+    /// </summary>
+    /// <exception cref="InvalidOperationException">Thrown if there are still allocated buffers that have not been freed.</exception>
     public static void Dispose()
     {
         _arena.Dispose();
+
+        nuint unfreedBytes = 0u;
+        while (_allocated.TryDequeue(out var allocationInfo))
+        {
+            unfreedBytes += allocationInfo.size;
+            AlignedFree(allocationInfo.ptr);
+        }
+
+        _allocated.Dispose();
+
+        if (unfreedBytes > 0u)
+        {
+            throw new InvalidOperationException($"There are still {unfreedBytes} bytes allocated buffers. Please free them before disposing.");
+        }
     }
 }