Add Stream Span/Buffer-based APIs

[stephentoub]

Separated out of https://github.com/dotnet/corefx/issues/21281 for tracking purposes.

• Implement span-based APIs in System.Private.CoreLib in coreclr
• Implement buffer-based APIs in System.Private.CoreLib in coreclr
• Implement span-based APIs in System.Private.CoreLib in corert (if Stream isn't yet in "shared")
• Implement buffer-based APIs in System.Private.CoreLib in corert (if Stream isn't yet in "shared")
• Expose span-based APIs from System.Runtime contract in corefx
• Expose buffer-based APIs from System.Runtime contract in corefx
• Add span-based APIs tests to System.Runtime tests in corefx
• Add buffer-based APIs tests to System.Runtime tests in corefx

namespace System.IO
{
    public class Stream
    {
        public virtual int Read(Span<byte> destination);
        public virtual ValueTask<int> ReadAsync(Buffer<byte> destination, CancellationToken cancellationToken = default(CancellationToken));

        public virtual void Write(ReadOnlySpan<byte> source);
        public virtual Task WriteAsync(ReadOnlyBuffer<byte> source, CancellationToken cancellationToken = default(CancellationToken));
        …
    }
}

[sharwell]

💡 Can start writing = default for the default value, assuming you don't want to go the actual right way and make it required. 😉

[jnm2]

++ for the actual right way 😄

[tdinucci]

@stephentoub there's more than a slim chance that I'm missing something but I don't understand the purpose of the new Span-based Read/Write methods on Stream since the default implementations seem to introduce overhead above that of the array based overloads.

When would/should I choose to call the Span-based versions?

[stephentoub]

since the default implementations seem to introduce overhead above that of the array based overloads

Those default implementations only exist for cases where derived Streams don't override them. Every important stream in .NET Core does override them, and once this ships, we hope/expect other streams will as well.

[tdinucci]

Thanks @stephentoub, I did wonder if it was just so you could have extra flexibility for Stream derivatives but I still couldn't understand where you would get a benefit from this flexibility (in the Stream.Read/Write case, I can see benefit in other areas).

What would be a good use case for choosing MemoryStream.Read(Span..) over the overload that takes an array?

[stephentoub]

What would be a good use case for choosing MemoryStream.Read(Span..) over the overload that takes an array?

a) You have a span as input.
b) You want to avoid the Task<int> allocation.

[KubaO]

@tdinucci The use of byte[] as a stand-in for "a buffer of bytes" was just a very long-standing broken API to begin with. It looked familiar to C developers, but was very hard to use in safe code. With spans and buffers there's no reason to even use the array-based API, and you can do every manipulation imaginable in a safe fashion. I wish the array-based APIs were deprecated already... They are useless, since arrays implicitly convert to Span, if you insist on using arrays to begin with (Memory expresses intent better).