Merge pull request #3353 from Sergio0694/feature/array3d-apis

2D System.Memory-like primitives (Span2D<T>, Memory2D<T>)

Author: michael-hawker

Microsoft.Toolkit.HighPerformance/Buffers/ArrayPoolBufferWriter{T}.cs

@@ -24,7 +24,7 @@ namespace Microsoft.Toolkit.HighPerformance.Buffers
     /// the arrays in use are rented from the shared <see cref="ArrayPool{T}"/> instance,
     /// and that <see cref="ArrayPoolBufferWriter{T}"/> is also available on .NET Standard 2.0.
     /// </remarks>
-    [DebuggerTypeProxy(typeof(ArrayPoolBufferWriterDebugView<>))]
+    [DebuggerTypeProxy(typeof(MemoryDebugView<>))]
     [DebuggerDisplay("{ToString(),raw}")]
     public sealed class ArrayPoolBufferWriter<T> : IBuffer<T>, IMemoryOwner<T>
     {

Microsoft.Toolkit.HighPerformance/Buffers/Internals/RawObjectMemoryManager{T}.cs

@@ -0,0 +1,98 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information.
+
+#if SPAN_RUNTIME_SUPPORT
+
+using System;
+using System.Buffers;
+using System.Runtime.CompilerServices;
+using System.Runtime.InteropServices;
+using Microsoft.Toolkit.HighPerformance.Extensions;
+
+namespace Microsoft.Toolkit.HighPerformance.Buffers.Internals
+{
+    /// <summary>
+    /// A custom <see cref="MemoryManager{T}"/> that can wrap arbitrary <see cref="object"/> instances.
+    /// </summary>
+    /// <typeparam name="T">The type of elements in the target memory area.</typeparam>
+    internal sealed class RawObjectMemoryManager<T> : MemoryManager<T>
+    {
+        /// <summary>
+        /// The target <see cref="object"/> instance.
+        /// </summary>
+        private readonly object instance;
+
+        /// <summary>
+        /// The initial offset within <see cref="instance"/>.
+        /// </summary>
+        private readonly IntPtr offset;
+
+        /// <summary>
+        /// The length of the target memory area.
+        /// </summary>
+        private readonly int length;
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="RawObjectMemoryManager{T}"/> class.
+        /// </summary>
+        /// <param name="instance">The target <see cref="object"/> instance.</param>
+        /// <param name="offset">The starting offset within <paramref name="instance"/>.</param>
+        /// <param name="length">The usable length within <paramref name="instance"/>.</param>
+        public RawObjectMemoryManager(object instance, IntPtr offset, int length)
+        {
+            this.instance = instance;
+            this.offset = offset;
+            this.length = length;
+        }
+
+        /// <inheritdoc/>
+        public override Span<T> GetSpan()
+        {
+            ref T r0 = ref this.instance.DangerousGetObjectDataReferenceAt<T>(this.offset);
+
+            return MemoryMarshal.CreateSpan(ref r0, this.length);
+        }
+
+        /// <inheritdoc/>
+        public override unsafe MemoryHandle Pin(int elementIndex = 0)
+        {
+            if ((uint)elementIndex >= (uint)this.length)
+            {
+                ThrowArgumentOutOfRangeExceptionForInvalidElementIndex();
+            }
+
+            // Allocating a pinned handle for the array with fail and throw an exception
+            // if the array contains non blittable data. This is the expected behavior and
+            // the same happens when trying to pin a Memory<T> instance obtained through
+            // traditional means (eg. via the implicit T[] array conversion), if T is a
+            // reference type or a type containing some references.
+            GCHandle handle = GCHandle.Alloc(this.instance, GCHandleType.Pinned);
+            ref T r0 = ref this.instance.DangerousGetObjectDataReferenceAt<T>(this.offset);
+            ref T r1 = ref Unsafe.Add(ref r0, (nint)(uint)elementIndex);
+            void* p = Unsafe.AsPointer(ref r1);
+
+            return new MemoryHandle(p, handle);
+        }
+
+        /// <inheritdoc/>
+        public override void Unpin()
+        {
+        }
+
+        /// <inheritdoc/>
+        protected override void Dispose(bool disposing)
+        {
+        }
+
+        /// <summary>
+        /// Throws an <see cref="ArgumentOutOfRangeException"/> when the input index for <see cref="Pin"/> is not valid.
+        /// </summary>
+        private static void ThrowArgumentOutOfRangeExceptionForInvalidElementIndex()
+        {
+            throw new ArgumentOutOfRangeException("elementIndex", "The input element index was not in the valid range");
+        }
+    }
+}
+
+#endif

Microsoft.Toolkit.HighPerformance/Buffers/MemoryBufferWriter{T}.cs

@@ -7,6 +7,7 @@
 using System.Diagnostics;
 using System.Diagnostics.Contracts;
 using System.Runtime.CompilerServices;
+using Microsoft.Toolkit.HighPerformance.Buffers.Views;
 
 namespace Microsoft.Toolkit.HighPerformance.Buffers
 {
@@ -20,7 +21,7 @@ namespace Microsoft.Toolkit.HighPerformance.Buffers
     /// instances (or objects that can be converted to a <see cref="Memory{T}"/>), to ensure the data is written directly
     /// to the intended buffer, with no possibility of doing additional allocations or expanding the available capacity.
     /// </remarks>
-    [DebuggerTypeProxy(typeof(MemoryBufferWriter<>))]
+    [DebuggerTypeProxy(typeof(MemoryDebugView<>))]
     [DebuggerDisplay("{ToString(),raw}")]
     public sealed class MemoryBufferWriter<T> : IBuffer<T>
     {

Microsoft.Toolkit.HighPerformance/Buffers/MemoryOwner{T}.cs

@@ -16,7 +16,7 @@ namespace Microsoft.Toolkit.HighPerformance.Buffers
     /// An <see cref="IMemoryOwner{T}"/> implementation with an embedded length and a fast <see cref="Span{T}"/> accessor.
     /// </summary>
     /// <typeparam name="T">The type of items to store in the current instance.</typeparam>
-    [DebuggerTypeProxy(typeof(MemoryOwnerDebugView<>))]
+    [DebuggerTypeProxy(typeof(MemoryDebugView<>))]
     [DebuggerDisplay("{ToString(),raw}")]
     public sealed class MemoryOwner<T> : IMemoryOwner<T>
     {

Microsoft.Toolkit.HighPerformance/Buffers/SpanOwner{T}.cs

@@ -31,7 +31,7 @@ namespace Microsoft.Toolkit.HighPerformance.Buffers
     /// Not doing so will cause the underlying buffer not to be returned to the shared pool.
     /// </summary>
     /// <typeparam name="T">The type of items to store in the current instance.</typeparam>
-    [DebuggerTypeProxy(typeof(SpanOwnerDebugView<>))]
+    [DebuggerTypeProxy(typeof(MemoryDebugView<>))]
     [DebuggerDisplay("{ToString(),raw}")]
     public readonly ref struct SpanOwner<T>
     {

Microsoft.Toolkit.HighPerformance/Buffers/StringPool.cs

@@ -536,7 +536,7 @@ private unsafe ref string TryGet(ReadOnlySpan<char> span, int hashcode)
                      (uint)i < (uint)length;
                      i = entry.NextIndex)
                 {
-                    entry = ref Unsafe.Add(ref mapEntriesRef, (IntPtr)(void*)(uint)i);
+                    entry = ref Unsafe.Add(ref mapEntriesRef, (nint)(uint)i);
 
                     if (entry.HashCode == hashcode &&
                         entry.Value!.AsSpan().SequenceEqual(span))
@@ -556,7 +556,7 @@ private unsafe ref string TryGet(ReadOnlySpan<char> span, int hashcode)
             /// <param name="value">The new <see cref="string"/> instance to store.</param>
             /// <param name="hashcode">The precomputed hashcode for <paramref name="value"/>.</param>
             [MethodImpl(MethodImplOptions.NoInlining)]
-            private unsafe void Insert(string value, int hashcode)
+            private void Insert(string value, int hashcode)
             {
                 ref int bucketsRef = ref this.buckets.DangerousGetReference();
                 ref MapEntry mapEntriesRef = ref this.mapEntries.DangerousGetReference();
@@ -571,7 +571,7 @@ private unsafe void Insert(string value, int hashcode)
                     entryIndex = heapEntriesRef.MapIndex;
                     heapIndex = 0;
 
-                    ref MapEntry removedEntry = ref Unsafe.Add(ref mapEntriesRef, (IntPtr)(void*)(uint)entryIndex);
+                    ref MapEntry removedEntry = ref Unsafe.Add(ref mapEntriesRef, (nint)(uint)entryIndex);
 
                     // The removal logic can be extremely optimized in this case, as we
                     // can retrieve the precomputed hashcode for the target entry by doing
@@ -588,9 +588,9 @@ private unsafe void Insert(string value, int hashcode)
                 }
 
                 int bucketIndex = hashcode & (this.buckets.Length - 1);
-                ref int targetBucket = ref Unsafe.Add(ref bucketsRef, (IntPtr)(void*)(uint)bucketIndex);
-                ref MapEntry targetMapEntry = ref Unsafe.Add(ref mapEntriesRef, (IntPtr)(void*)(uint)entryIndex);
-                ref HeapEntry targetHeapEntry = ref Unsafe.Add(ref heapEntriesRef, (IntPtr)(void*)(uint)heapIndex);
+                ref int targetBucket = ref Unsafe.Add(ref bucketsRef, (nint)(uint)bucketIndex);
+                ref MapEntry targetMapEntry = ref Unsafe.Add(ref mapEntriesRef, (nint)(uint)entryIndex);
+                ref HeapEntry targetHeapEntry = ref Unsafe.Add(ref heapEntriesRef, (nint)(uint)heapIndex);
 
                 // Assign the values in the new map entry
                 targetMapEntry.HashCode = hashcode;
@@ -616,7 +616,7 @@ private unsafe void Insert(string value, int hashcode)
             /// <param name="mapIndex">The index of the target map node to remove.</param>
             /// <remarks>The input <see cref="string"/> instance needs to already exist in the map.</remarks>
             [MethodImpl(MethodImplOptions.NoInlining)]
-            private unsafe void Remove(int hashcode, int mapIndex)
+            private void Remove(int hashcode, int mapIndex)
             {
                 ref MapEntry mapEntriesRef = ref this.mapEntries.DangerousGetReference();
                 int
@@ -628,15 +628,15 @@ private unsafe void Remove(int hashcode, int mapIndex)
                 // value we're looking for is guaranteed to be present
                 while (true)
                 {
-                    ref MapEntry candidate = ref Unsafe.Add(ref mapEntriesRef, (IntPtr)(void*)(uint)entryIndex);
+                    ref MapEntry candidate = ref Unsafe.Add(ref mapEntriesRef, (nint)(uint)entryIndex);
 
                     // Check the current value for a match
                     if (entryIndex == mapIndex)
                     {
                         // If this was not the first list node, update the parent as well
                         if (lastIndex != EndOfList)
                         {
-                            ref MapEntry lastEntry = ref Unsafe.Add(ref mapEntriesRef, (IntPtr)(void*)(uint)lastIndex);
+                            ref MapEntry lastEntry = ref Unsafe.Add(ref mapEntriesRef, (nint)(uint)lastIndex);
 
                             lastEntry.NextIndex = candidate.NextIndex;
                         }
@@ -662,14 +662,14 @@ private unsafe void Remove(int hashcode, int mapIndex)
             /// </summary>
             /// <param name="heapIndex">The index of the target heap node to update.</param>
             [MethodImpl(MethodImplOptions.NoInlining)]
-            private unsafe void UpdateTimestamp(ref int heapIndex)
+            private void UpdateTimestamp(ref int heapIndex)
             {
                 int
                     currentIndex = heapIndex,
                     count = this.count;
                 ref MapEntry mapEntriesRef = ref this.mapEntries.DangerousGetReference();
                 ref HeapEntry heapEntriesRef = ref this.heapEntries.DangerousGetReference();
-                ref HeapEntry root = ref Unsafe.Add(ref heapEntriesRef, (IntPtr)(void*)(uint)currentIndex);
+                ref HeapEntry root = ref Unsafe.Add(ref heapEntriesRef, (nint)(uint)currentIndex);
                 uint timestamp = this.timestamp;
 
                 // Check if incrementing the current timestamp for the heap node to update
@@ -721,7 +721,7 @@ private unsafe void UpdateTimestamp(ref int heapIndex)
                     // Check and update the left child, if necessary
                     if (left < count)
                     {
-                        ref HeapEntry child = ref Unsafe.Add(ref heapEntriesRef, (IntPtr)(void*)(uint)left);
+                        ref HeapEntry child = ref Unsafe.Add(ref heapEntriesRef, (nint)(uint)left);
 
                         if (child.Timestamp < minimum.Timestamp)
                         {
@@ -733,7 +733,7 @@ private unsafe void UpdateTimestamp(ref int heapIndex)
                     // Same check as above for the right child
                     if (right < count)
                     {
-                        ref HeapEntry child = ref Unsafe.Add(ref heapEntriesRef, (IntPtr)(void*)(uint)right);
+                        ref HeapEntry child = ref Unsafe.Add(ref heapEntriesRef, (nint)(uint)right);
 
                         if (child.Timestamp < minimum.Timestamp)
                         {
@@ -752,8 +752,8 @@ private unsafe void UpdateTimestamp(ref int heapIndex)
                     }
 
                     // Update the indices in the respective map entries (accounting for the swap)
-                    Unsafe.Add(ref mapEntriesRef, (IntPtr)(void*)(uint)root.MapIndex).HeapIndex = targetIndex;
-                    Unsafe.Add(ref mapEntriesRef, (IntPtr)(void*)(uint)minimum.MapIndex).HeapIndex = currentIndex;
+                    Unsafe.Add(ref mapEntriesRef, (nint)(uint)root.MapIndex).HeapIndex = targetIndex;
+                    Unsafe.Add(ref mapEntriesRef, (nint)(uint)minimum.MapIndex).HeapIndex = currentIndex;
 
                     currentIndex = targetIndex;
 
@@ -764,7 +764,7 @@ private unsafe void UpdateTimestamp(ref int heapIndex)
                     minimum = temp;
 
                     // Update the reference to the root node
-                    root = ref Unsafe.Add(ref heapEntriesRef, (IntPtr)(void*)(uint)currentIndex);
+                    root = ref Unsafe.Add(ref heapEntriesRef, (nint)(uint)currentIndex);
                 }
 
                 Fallback:
@@ -787,14 +787,14 @@ private unsafe void UpdateTimestamp(ref int heapIndex)
             /// a given number of nodes, those are all contiguous from the start of the array.
             /// </summary>
             [MethodImpl(MethodImplOptions.NoInlining)]
-            private unsafe void UpdateAllTimestamps()
+            private void UpdateAllTimestamps()
             {
                 int count = this.count;
                 ref HeapEntry heapEntriesRef = ref this.heapEntries.DangerousGetReference();
 
                 for (int i = 0; i < count; i++)
                 {
-                    Unsafe.Add(ref heapEntriesRef, (IntPtr)(void*)(uint)i).Timestamp = (uint)i;
+                    Unsafe.Add(ref heapEntriesRef, (nint)(uint)i).Timestamp = (uint)i;
                 }
             }
         }