Improve API by introducing TlsfAllocationToken

src/XenoAtom.Allocators/TlsfAllocation.cs

@@ -9,17 +9,17 @@ namespace XenoAtom.Allocators;
 /// </summary>
 public readonly record struct TlsfAllocation
 {
-    internal TlsfAllocation(uint blockIndex, MemoryAddress address, MemorySize size)
+    internal TlsfAllocation(TlsfAllocationToken token, MemoryAddress address, MemorySize size)
     {
-        BlockIndex = blockIndex;
+        Token = token;
         Address = address;
         Size = size;
     }
 
     /// <summary>
     /// Gets the index of the block allocated (used internally by the allocator).
     /// </summary>
-    internal readonly uint BlockIndex;
+    public readonly TlsfAllocationToken Token;
 
     /// <summary>
     /// Gets the address of the allocated block.
@@ -30,4 +30,9 @@ internal TlsfAllocation(uint blockIndex, MemoryAddress address, MemorySize size)
     /// Gets the size of the allocated block.
     /// </summary>
     public readonly MemorySize Size;
+
+    /// <summary>
+    /// Implicit conversion to <see cref="TlsfAllocationToken"/>.
+    /// </summary>
+    public static implicit operator TlsfAllocationToken (TlsfAllocation allocation) => allocation.Token;
 }

src/XenoAtom.Allocators/TlsfAllocationToken.cs

@@ -0,0 +1,21 @@
+// Copyright (c) Alexandre Mutel. All rights reserved.
+// Licensed under the BSD-Clause 2 license.
+// See license.txt file in the project root for full license information.
+
+namespace XenoAtom.Allocators;
+
+/// <summary>
+/// A token representing an allocation from a <see cref="TlsfAllocator"/> returned by <see cref="TlsfAllocation.Token"/>.
+/// </summary>
+public readonly record struct TlsfAllocationToken
+{
+    internal TlsfAllocationToken(uint blockIndex)
+    {
+        BlockIndex = blockIndex;
+    }
+
+    internal readonly uint BlockIndex;
+
+    /// <inheritdoc />
+    public override string ToString() => $"TlsfAllocationToken({BlockIndex})";
+}

src/XenoAtom.Allocators/TlsfAllocator.cs

@@ -154,7 +154,7 @@ public TlsfAllocation Allocate(uint size)
                 InsertBlockIntoFreeList(ref freeBlock, freeBlockIndex, newFirstLevelIndex, newSecondLevelIndex);
             }
 
-            return new TlsfAllocation((uint)usedBlockIndex, (ulong)chunk.Info.BaseAddress + offsetIntoChunk, size);
+            return new TlsfAllocation(new((uint)usedBlockIndex), (ulong)chunk.Info.BaseAddress + offsetIntoChunk, size);
         }
         else
         {
@@ -168,25 +168,25 @@ public TlsfAllocation Allocate(uint size)
             chunk.FreeBlockCount--;
             Debug.Assert(chunk.FreeBlockCount >= 0);
 
-            return new TlsfAllocation((uint)freeBlockIndex, (ulong)chunk.Info.BaseAddress + offsetIntoChunk, size);
+            return new TlsfAllocation(new((uint)freeBlockIndex), (ulong)chunk.Info.BaseAddress + offsetIntoChunk, size);
         }
     }
 
     /// <summary>
     /// Frees an allocation.
     /// </summary>
-    /// <param name="allocation">An allocation unit to free.</param>
-    public void Free(TlsfAllocation allocation)
+    /// <param name="allocationToken">The allocation token to free.</param>
+    public void Free(TlsfAllocationToken allocationToken)
     {
-        int blockIndex = (int)allocation.BlockIndex;
+        int blockIndex = (int)allocationToken.BlockIndex;
         if ((uint)blockIndex >= (uint)_blockCount)
         {
-            throw new ArgumentException($"The block index {blockIndex} is out of range", nameof(allocation));
+            throw new ArgumentException($"The block index {blockIndex} is out of range", nameof(allocationToken));
         }
         ref var block = ref GetBlockAt(blockIndex);
         if (!block.IsUsed)
         {
-            throw new ArgumentException($"The block at index {blockIndex} is already free", nameof(allocation));
+            throw new ArgumentException($"The block at index {blockIndex} is already free", nameof(allocationToken));
         }
         block.IsUsed = false;