[API Proposal]: Stream APIs - GetDirectSpan & ReadDirectSpan

[conmaster2112]

Background and motivation

I've been using Stream APIs for some time now and in many cases memory is often copied when reading, and for that reason there are internal functions that solve these shortcomings, although some internal functions solve this, but they are not available to us as end users.

I would like to talk about the relationship between BinaryReader and MemoryStream in details.

BinaryReader

As for BinaryReader, it is a very useful class that could also be extended by child classes. Did i say could? So it's not possible? As for C# rules, sure, but if I want to add or override an existing write method, I end up with very disgusting performance, because it's fast natively, it's only thanks to internal workarounds.

Resources And Links

• BinaryReader Internal Read
• MemoryStream Internal Read

Yes, I can create my own MemoryStream and my own BinaryWriter/BinaryReader, but then it loses its compatibility with both 3rd-party and native libraries.

Solution

The answer to these things would be two new methods for the base Steam class.

• void virtual ReadOnlySpan<byte> DirectRead(int length)
• void virtual Span<byte> DirectGet(int length, bool moveCursor = true)
  Both of these methods should all round speed up the old stream APIs and avoid unnecessary heap memory allocation and unnecessary memory copying.

API Proposal

Proposal Concept

namespace System.IO;


public abstract class Stream
{
    public virtual bool CanDirectRead { get => false; }
    public virtual ReadOnlySpan<byte> DirectRead(int length)
    {
        throw new NotImplementedException();
    }
    public virtual Span<byte> DirectGet(int length, bool moveCursor)
    {
        throw new NotImplementedException();
    }
}
public class MemoryStream: Stream
{
    public override bool CanDirectRead { get => true; }
    public override ReadOnlySpan<byte> DirectRead(int length)
    {
        EnsureNotClosed();

        int origPos = _position;
        int newPos = origPos + count;

        if ((uint)newPos > (uint)_length)
        {
            _position = _length;
            ThrowHelper.ThrowEndOfFileException();
        }

        var span = new ReadOnlySpan<byte>(_buffer, origPos, count);
        _position = newPos;
        return span;
    }
    public override Span<byte> DirectGet(int length, bool moveCursor = true)
    {

        EnsureNotClosed();

        // if(!CanWrite) throw ... 
        
        int origPos = _position;
        int newPos = origPos + count;

        if ((uint)newPos > (uint)_length)
        {
            _position = _length;
            ThrowHelper.ThrowEndOfFileException();
        }

        var span = new Span<byte>(_buffer, origPos, count);
        if(moveCursor) _position = newPos;
        return span;
    }
}

public class BinaryReader
{
    //Internal re-implementation
    private ReadOnlySpan<byte> InternalRead(Span<byte> buffer)
    {
        Debug.Assert(buffer.Length != 1, "length of 1 should use ReadByte.");

        if (_stream.CanDirectRead)
        {
            /* Previose method
                // read directly from MemoryStream buffer
                Debug.Assert(_stream is MemoryStream);
                return Unsafe.As<MemoryStream>(_stream).InternalReadSpan(buffer.Length);
            */
            return _stream.DirectRead(buffer.Length);
        }
        else
        {
            ThrowIfDisposed();

            _stream.ReadExactly(buffer);

            return buffer;
        }
    }
}

API Usage

Pseudo Concept Example - Custom Binary Reader

//Initialize own exteneded implementation of BinaryReader
using MyBinaryReader reader = new MyBinaryReader(new MemoryStream(packet));

//Read int in my own way!!!
int myInt = reader.ReadInt32BigEndian();

Pseudo Concept Example - Custom MemoryStream

//Initialize BinaryReader with own MemoryStream implementation
using BinaryReader reader = new BinaryReader(new MyMemoryStream(packet));

//Read int really fast!!!
int myInt = reader.ReadInt32();

Alternative Designs

The examples given above solve two birds with one stone, both the acceleration of reading from MemoryStream and the extensibility of BineryReader.

Another possibility would be to publish the internal method InternalRead in the BineryReader class, but that would not change anything, since the binary reader would also read slowly from memory streams other than the native one. (Its Hardcoded)

Also keep in mind that descendant of the MemoryStream class is not marked as MemoryStream for BinaryReader as well, so that results in slow reading from descendants of MemoryStream class.

Risks

The method name can be misleading for beginners, and for most stream implementations it will throw an exception NotImplementedException.

[dotnet-policy-service]

Tagging subscribers to this area: @dotnet/area-system-io
See info in area-owners.md if you want to be subscribed.

[jozkee]

Related: #106524.

[conmaster2112]

Thanks, well let me close it for now.