Document span lifetime issue in CreateSpan (dotnet/corefxdotnet/coreclr#30490) (dotne...

The language rules around span safety that C# and F# adhere to assume
there is no way to create a `Span<T>` wrapper over a `ref` local /
parameter. This means `ref` inputs into a method are not considered when
calculating the allowed lifetime of a returned `Span<T>`. Hence both
CreateSpan and CreateReadOnlySpan will be assumed to have heap lifetime
even when provided stack based inputs. Example:

``` c#
Span<int> Example() {
  int i = 42;
  Span<int> span = MemoryMarshal.CreateSpan(ref i, length: 1);
  return span; // C# and F# will allow this
}
```

In this case the actual lifetime of `span` is that of `i`. Yet the
compiler doesn't consider the `ref i` input and hence believes this must
be heap based and hence safe to return out of the method.

This is okay as these methods are unsafe. But want to explicitly
document that fact.

More information on the safety rules can be found in the [span safety
proposal](https://github.com/dotnet/csharplang/blob/master/proposals/csharp-7.2/span-safety.md)

Signed-off-by: dotnet-bot-corefx-mirror <dotnet-bot@microsoft.com>
Commit migrated from https://github.com/dotnet/coreclr/commit/ac637552982717e72e473df03d0994e65c2dccd8

diff --git a/src/libraries/System.Private.CoreLib/src/System/Runtime/InteropServices/MemoryMarshal.Fast.cs b/src/libraries/System.Private.CoreLib/src/System/Runtime/InteropServices/MemoryMarshal.Fast.cs
index e212f7d..c71c782 100644 (file)
--- a/src/libraries/System.Private.CoreLib/src/System/Runtime/InteropServices/MemoryMarshal.Fast.cs
+++ b/src/libraries/System.Private.CoreLib/src/System/Runtime/InteropServices/MemoryMarshal.Fast.cs
@@ -214,6 +214,7 @@ namespace System.Runtime.InteropServices
         /// </summary>
         /// <param name="reference">A reference to data.</param>
         /// <param name="length">The number of <typeparamref name="T"/> elements the memory contains.</param>
+        /// <returns>The lifetime of the returned span will not be validated for safety by span-aware languages.</returns>
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
         public static Span<T> CreateSpan<T>(ref T reference, int length) => new Span<T>(ref reference, length);
 
@@ -224,6 +225,7 @@ namespace System.Runtime.InteropServices
         /// </summary>
         /// <param name="reference">A reference to data.</param>
         /// <param name="length">The number of <typeparamref name="T"/> elements the memory contains.</param>
+        /// <returns>The lifetime of the returned span will not be validated for safety by span-aware languages.</returns>
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
         public static ReadOnlySpan<T> CreateReadOnlySpan<T>(ref T reference, int length) => new ReadOnlySpan<T>(ref reference, length);
     }