Add Memory.Pin() to eventually replace Memory.Retain(bool)

src/Common/src/CoreLib/System/IO/FileStreamCompletionSource.Win32.cs

@@ -246,7 +246,7 @@ private sealed class MemoryFileStreamCompletionSource : FileStreamCompletionSour
             internal MemoryFileStreamCompletionSource(FileStream stream, int numBufferedBytes, ReadOnlyMemory<byte> memory) :
                 base(stream, numBufferedBytes, bytes: null) // this type handles the pinning, so null is passed for bytes
             {
-                _handle = memory.Retain(pin: true);
+                _handle = memory.Pin();
             }
 
             internal override void ReleaseNativeResource()

src/Common/src/Interop/Unix/System.Security.Cryptography.Native/Interop.OpenSsl.cs

@@ -232,7 +232,7 @@ internal static int Encrypt(SafeSslHandle context, ReadOnlyMemory<byte> input, r
             int retVal;
             unsafe
             {
-                using (MemoryHandle handle = input.Retain(pin: true))
+                using (MemoryHandle handle = input.Pin())
                 {
                     retVal = Ssl.SslWrite(context, (byte*)handle.Pointer, input.Length);
                 }

src/System.IO.Compression/src/System/IO/Compression/DeflateZLib/Deflater.cs

@@ -100,7 +100,7 @@ internal unsafe void SetInput(ReadOnlyMemory<byte> inputBuffer)
 
             lock (SyncLock)
             {
-                _inputBufferHandle = inputBuffer.Retain(pin: true);
+                _inputBufferHandle = inputBuffer.Pin();
 
                 _zlibStream.NextIn = (IntPtr)_inputBufferHandle.Pointer;
                 _zlibStream.AvailIn = (uint)inputBuffer.Length;

src/System.IO.Pipes/src/System/IO/Pipes/PipeCompletionSource.cs

@@ -40,7 +40,7 @@ protected PipeCompletionSource(ThreadPoolBoundHandle handle, ReadOnlyMemory<byte
             _threadPoolBinding = handle;
             _state = NoResult;
 
-            _pinnedMemory = bufferToPin.Retain(pin: true);
+            _pinnedMemory = bufferToPin.Pin();
             _overlapped = _threadPoolBinding.AllocateNativeOverlapped((errorCode, numBytes, pOverlapped) =>
             {
                 var completionSource = (PipeCompletionSource<TResult>)ThreadPoolBoundHandle.GetNativeOverlappedState(pOverlapped);

src/System.Memory/ref/System.Memory.cs

@@ -107,6 +107,7 @@ public void CopyTo(System.Memory<T> destination) { }
         public static implicit operator System.Memory<T> (System.ArraySegment<T> segment) { throw null; }
         public static implicit operator System.ReadOnlyMemory<T> (System.Memory<T> memory) { throw null; }
         public static implicit operator System.Memory<T> (T[] array) { throw null; }
+        public System.Buffers.MemoryHandle Pin() { throw null; }
         public System.Buffers.MemoryHandle Retain(bool pin = false) { throw null; }
         public System.Memory<T> Slice(int start) { throw null; }
         public System.Memory<T> Slice(int start, int length) { throw null; }
@@ -131,6 +132,7 @@ public void CopyTo(System.Memory<T> destination) { }
         public override int GetHashCode() { throw null; }
         public static implicit operator System.ReadOnlyMemory<T> (System.ArraySegment<T> segment) { throw null; }
         public static implicit operator System.ReadOnlyMemory<T> (T[] array) { throw null; }
+        public System.Buffers.MemoryHandle Pin() { throw null; }
         public System.Buffers.MemoryHandle Retain(bool pin = false) { throw null; }
         public System.ReadOnlyMemory<T> Slice(int start) { throw null; }
         public System.ReadOnlyMemory<T> Slice(int start, int length) { throw null; }

src/System.Memory/tests/Memory/Pin.cs

@@ -0,0 +1,133 @@
+// 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.
+
+using System.Buffers;
+using Xunit;
+
+namespace System.MemoryTests
+{
+    public static partial class MemoryTests
+    {
+        [Fact]
+        public static void MemoryPin()
+        {
+            int[] array = { 1, 2, 3, 4, 5 };
+            Memory<int> memory = array;
+            MemoryHandle handle = memory.Pin();
+            Assert.True(handle.HasPointer);
+            unsafe
+            {
+                int* pointer = (int*)handle.Pointer;
+
+                GC.Collect();
+
+                for (int i = 0; i < memory.Length; i++)
+                {
+                    Assert.Equal(array[i], pointer[i]);
+                }
+            }
+            handle.Dispose();
+        }
+
+        [Fact]
+        public static void MemoryFromEmptyArrayPin()
+        {
+            Memory<int> memory = new int[0];
+            MemoryHandle handle = memory.Pin();
+            Assert.True(handle.HasPointer);
+            handle.Dispose();
+        }
+
+        [Fact]
+        public static void DefaultMemoryPin()
+        {
+            Memory<int> memory = default;
+            MemoryHandle handle = memory.Pin();
+            Assert.False(handle.HasPointer);
+            unsafe
+            {
+                Assert.True(handle.Pointer == null);
+            }
+            handle.Dispose();
+        }
+
+        [Fact]
+        public static void MemoryPinAndSlice()
+        {
+            int[] array = { 1, 2, 3, 4, 5 };
+            Memory<int> memory = array;
+            memory = memory.Slice(1);
+            MemoryHandle handle = memory.Pin();
+            Span<int> span = memory.Span;
+            Assert.True(handle.HasPointer);
+            unsafe
+            {
+                int* pointer = (int*)handle.Pointer;
+
+                GC.Collect();
+
+                for (int i = 0; i < memory.Length; i++)
+                {
+                    Assert.Equal(array[i + 1], pointer[i]);
+                }
+
+                for (int i = 0; i < memory.Length; i++)
+                {
+                    Assert.Equal(array[i + 1], span[i]);
+                }
+            }
+            handle.Dispose();
+        }
+
+        [Fact]
+        public static void OwnedMemoryPin()
+        {
+            int[] array = { 1, 2, 3, 4, 5 };
+            OwnedMemory<int> owner = new CustomMemoryForTest<int>(array);
+            Memory<int> memory = owner.Memory;
+            MemoryHandle handle = memory.Pin();
+            Assert.True(handle.HasPointer);
+            unsafe
+            {
+                int* pointer = (int*)handle.Pointer;
+
+                GC.Collect();
+
+                for (int i = 0; i < memory.Length; i++)
+                {
+                    Assert.Equal(array[i], pointer[i]);
+                }
+            }
+            handle.Dispose();
+        }
+
+        [Fact]
+        public static void OwnedMemoryPinAndSlice()
+        {
+            int[] array = { 1, 2, 3, 4, 5 };
+            OwnedMemory<int> owner = new CustomMemoryForTest<int>(array);
+            Memory<int> memory = owner.Memory.Slice(1);
+            MemoryHandle handle = memory.Pin();
+            Span<int> span = memory.Span;
+            Assert.True(handle.HasPointer);
+            unsafe
+            {
+                int* pointer = (int*)handle.Pointer;
+
+                GC.Collect();
+
+                for (int i = 0; i < memory.Length; i++)
+                {
+                    Assert.Equal(array[i + 1], pointer[i]);
+                }
+
+                for (int i = 0; i < memory.Length; i++)
+                {
+                    Assert.Equal(array[i + 1], span[i]);
+                }
+            }
+            handle.Dispose();
+        }
+    }
+}

src/System.Memory/tests/Memory/Retain.cs

@@ -45,6 +45,30 @@ public static void MemoryRetainWithPinning()
             handle.Dispose();
         }
 
+        [Fact]
+        public static void MemoryFromEmptyArrayRetainWithPinning()
+        {
+            Memory<int> memory = new int[0];
+            MemoryHandle handle = memory.Retain(pin: true);
+            Assert.True(handle.HasPointer);
+            handle.Dispose();
+        }
+
+        [Theory]
+        [InlineData(true)]
+        [InlineData(false)]
+        public static void DefaultMemoryRetain(bool pin)
+        {
+            Memory<int> memory = default;
+            MemoryHandle handle = memory.Retain(pin: pin);
+            Assert.False(handle.HasPointer);
+            unsafe
+            {
+                Assert.True(handle.Pointer == null);
+            }
+            handle.Dispose();
+        }
+
         [Fact]
         public static void MemoryRetainWithPinningAndSlice()
         {
@@ -110,15 +134,6 @@ public static void OwnedMemoryRetainWithPinning()
             handle.Dispose();
         }
 
-        [Fact]
-        public static void MemoryFromEmptyArrayRetainWithPinning()
-        {
-            Memory<int> memory = new int[0];
-            MemoryHandle handle = memory.Retain(pin: true);
-            Assert.True(handle.HasPointer);
-            handle.Dispose();
-        }
-
         [Fact]
         public static void OwnedMemoryRetainWithPinningAndSlice()
         {
@@ -146,20 +161,5 @@ public static void OwnedMemoryRetainWithPinningAndSlice()
             }
             handle.Dispose();
         }
-
-        [Theory]
-        [InlineData(true)]
-        [InlineData(false)]
-        public static void DefaultMemoryRetain(bool pin)
-        {
-            Memory<int> memory = default;
-            MemoryHandle handle = memory.Retain(pin: pin);
-            Assert.False(handle.HasPointer);
-            unsafe
-            {
-                Assert.True(handle.Pointer == null);
-            }
-            handle.Dispose();
-        }
     }
 }

src/System.Memory/tests/Memory/Strings.cs

@@ -57,18 +57,13 @@ public static void Memory_Slice_MatchesSubstring(string input, int offset, int c
         }
 
         [Fact]
-        public static unsafe void Memory_Retain_ExpectedPointerValue()
+        public static unsafe void Memory_Pin_ExpectedPointerValue()
         {
             string input = "0123456789";
             ReadOnlyMemory<char> readonlyMemory = input.AsMemory();
             Memory<char> m = MemoryMarshal.AsMemory(readonlyMemory);
 
-            using (MemoryHandle h = m.Retain(pin: false))
-            {
-                Assert.Equal(IntPtr.Zero, (IntPtr)h.Pointer);
-            }
-
-            using (MemoryHandle h = m.Retain(pin: true))
+            using (MemoryHandle h = m.Pin())
             {
                 GC.Collect();
                 fixed (char* ptr = input)

src/System.Memory/tests/MemoryMarshal/AsMemory.cs

@@ -39,17 +39,17 @@ public static IEnumerable<object[]> ReadOnlyMemoryCharInstances()
 
         [Theory]
         [MemberData(nameof(ReadOnlyMemoryInt32Instances))]
-        public static void AsMemory_Roundtrips(ReadOnlyMemory<int> readOnlyMemory) => AsMemory_Roundtrips_Core(readOnlyMemory);
+        public static void AsMemory_Roundtrips(ReadOnlyMemory<int> readOnlyMemory) => AsMemory_Roundtrips_Core(readOnlyMemory, true);
 
         [Theory]
         [MemberData(nameof(ReadOnlyMemoryObjectInstances))]
-        public static void AsMemory_Roundtrips(ReadOnlyMemory<object> readOnlyMemory) => AsMemory_Roundtrips_Core(readOnlyMemory);
+        public static void AsMemory_Roundtrips(ReadOnlyMemory<object> readOnlyMemory) => AsMemory_Roundtrips_Core(readOnlyMemory, false);
 
         [Theory]
         [MemberData(nameof(ReadOnlyMemoryCharInstances))]
         public static void AsMemory_Roundtrips(ReadOnlyMemory<char> readOnlyMemory)
         {
-            AsMemory_Roundtrips_Core(readOnlyMemory);
+            AsMemory_Roundtrips_Core(readOnlyMemory, true);
 
             Memory<char> memory = MemoryMarshal.AsMemory(readOnlyMemory);
             ReadOnlyMemory<char> readOnlyClone = memory;
@@ -66,7 +66,7 @@ public static void AsMemory_Roundtrips(ReadOnlyMemory<char> readOnlyMemory)
             }
         }
 
-        private static unsafe void AsMemory_Roundtrips_Core<T>(ReadOnlyMemory<T> readOnlyMemory)
+        private static unsafe void AsMemory_Roundtrips_Core<T>(ReadOnlyMemory<T> readOnlyMemory, bool canBePinned)
         {
             Memory<T> memory = MemoryMarshal.AsMemory(readOnlyMemory);
             ReadOnlyMemory<T> readOnlyClone = memory;
@@ -87,13 +87,16 @@ private static unsafe void AsMemory_Roundtrips_Core<T>(ReadOnlyMemory<T> readOnl
             Assert.Equal(array1.Offset, array2.Offset);
             Assert.Equal(array1.Count, array2.Count);
 
-            // Retain
-            using (MemoryHandle readOnlyMemoryHandle = readOnlyMemory.Retain())
-            using (MemoryHandle readOnlyCloneHandle = readOnlyMemory.Retain())
-            using (MemoryHandle memoryHandle = readOnlyMemory.Retain())
+            if (canBePinned)
             {
-                Assert.Equal((IntPtr)readOnlyMemoryHandle.Pointer, (IntPtr)readOnlyCloneHandle.Pointer);
-                Assert.Equal((IntPtr)readOnlyMemoryHandle.Pointer, (IntPtr)memoryHandle.Pointer);
+                // Pin
+                using (MemoryHandle readOnlyMemoryHandle = readOnlyMemory.Pin())
+                using (MemoryHandle readOnlyCloneHandle = readOnlyMemory.Pin())
+                using (MemoryHandle memoryHandle = readOnlyMemory.Pin())
+                {
+                    Assert.Equal((IntPtr)readOnlyMemoryHandle.Pointer, (IntPtr)readOnlyCloneHandle.Pointer);
+                    Assert.Equal((IntPtr)readOnlyMemoryHandle.Pointer, (IntPtr)memoryHandle.Pointer);
+                }
             }
         }
     }