Introduced interfaces for buffered I/O

Author: sakno

src/DotNext.IO/Buffers/IBufferedChannel.cs

@@ -0,0 +1,19 @@
+using System.Buffers;
+
+namespace DotNext.Buffers;
+
+/// <summary>
+/// Represents buffered reader or writer.
+/// </summary>
+public interface IBufferedChannel : IResettable, IDisposable
+{
+    /// <summary>
+    /// Gets buffer allocator.
+    /// </summary>
+    MemoryAllocator<byte>? Allocator { get; init; }
+    
+    /// <summary>
+    /// Gets the maximum size of the internal buffer.
+    /// </summary>
+    int MaxBufferSize { get; init; }
+}

src/DotNext.IO/Buffers/IBufferedReader.cs

@@ -0,0 +1,52 @@
+namespace DotNext.Buffers;
+
+public interface IBufferedReader : IBufferedChannel
+{
+    /// <summary>
+    /// Gets unconsumed part of the buffer.
+    /// </summary>
+    ReadOnlyMemory<byte> Buffer { get; }
+
+    /// <summary>
+    /// Advances read position.
+    /// </summary>
+    /// <param name="count">The number of consumed bytes.</param>
+    /// <exception cref="ObjectDisposedException">The reader has been disposed.</exception>
+    /// <exception cref="ArgumentOutOfRangeException"><paramref name="count"/> is larger than the length of <see cref="Buffer"/>.</exception>
+    void Consume(int count);
+
+    /// <summary>
+    /// Fetches the data from the underlying storage to the internal buffer.
+    /// </summary>
+    /// <param name="token">The token that can be used to cancel the operation.</param>
+    /// <returns>
+    /// <see langword="true"/> if the data has been copied from the underlying storage to the internal buffer;
+    /// <see langword="false"/> if no more data to read.
+    /// </returns>
+    /// <exception cref="ObjectDisposedException">The reader has been disposed.</exception>
+    /// <exception cref="InternalBufferOverflowException">Internal buffer has no free space.</exception>
+    /// <exception cref="OperationCanceledException">The operation has been canceled.</exception>
+    ValueTask<bool> ReadAsync(CancellationToken token);
+
+    /// <summary>
+    /// Reads the block of the memory.
+    /// </summary>
+    /// <param name="destination">The output buffer.</param>
+    /// <param name="token">The token that can be used to cancel the operation.</param>
+    /// <returns>The number of bytes copied to <paramref name="destination"/>.</returns>
+    /// <exception cref="ObjectDisposedException">The reader has been disposed.</exception>
+    /// <exception cref="OperationCanceledException">The operation has been canceled.</exception>
+    async ValueTask<int> ReadAsync(Memory<byte> destination, CancellationToken token)
+    {
+        var result = 0;
+        for (int bytesRead; result < destination.Length; result += bytesRead, destination = destination.Slice(bytesRead))
+        {
+            Buffer.Span.CopyTo(destination.Span, out bytesRead);
+            Consume(bytesRead);
+            if (!await ReadAsync(token).ConfigureAwait(false))
+                break;
+        }
+
+        return result;
+    }
+}

src/DotNext.IO/Buffers/IBufferedWriter.cs

@@ -0,0 +1,73 @@
+using System.Buffers;
+
+namespace DotNext.Buffers;
+
+/// <summary>
+/// Represents buffered writer.
+/// </summary>
+public interface IBufferedWriter : IBufferedChannel, IBufferWriter<byte>
+{
+    /// <summary>
+    /// Marks the specified number of bytes in the buffer as produced.
+    /// </summary>
+    /// <param name="count">The number of produced bytes.</param>
+    /// <exception cref="ArgumentOutOfRangeException"><paramref name="count"/> is larger than the length of <see cref="Buffer"/>.</exception>
+    /// <exception cref="ObjectDisposedException">The writer has been disposed.</exception>
+    void Produce(int count);
+    
+    /// <summary>
+    /// The remaining part of the internal buffer available for write.
+    /// </summary>
+    /// <remarks>
+    /// The size of returned buffer may be less than or equal to <see cref="IBufferedChannel.MaxBufferSize"/>.
+    /// </remarks>
+    Memory<byte> Buffer { get; }
+
+    /// <summary>
+    /// Flushes buffered data to the underlying storage.
+    /// </summary>
+    /// <param name="token">The token that can be used to cancel the operation.</param>
+    /// <returns>The task representing asynchronous result.</returns>
+    /// <exception cref="ObjectDisposedException">The writer has been disposed.</exception>
+    /// <exception cref="OperationCanceledException">The operation has been canceled.</exception>
+    ValueTask WriteAsync(CancellationToken token);
+
+    /// <summary>
+    /// Writes the data to the underlying storage through the buffer.
+    /// </summary>
+    /// <param name="input">The input data to write.</param>
+    /// <param name="token">The token that can be used to cancel the operation.</param>
+    /// <returns>The task representing asynchronous result.</returns>
+    /// <exception cref="ObjectDisposedException">The object has been disposed.</exception>
+    /// <exception cref="OperationCanceledException">The operation has been canceled.</exception>
+    async ValueTask WriteAsync(ReadOnlyMemory<byte> input, CancellationToken token)
+    {
+        for (int bytesWritten; !input.IsEmpty; input = input.Slice(bytesWritten))
+        {
+            input.Span.CopyTo(Buffer.Span, out bytesWritten);
+            Produce(bytesWritten);
+            await WriteAsync(token).ConfigureAwait(false);
+        }
+    }
+    
+    /// <inheritdoc />
+    void IBufferWriter<byte>.Advance(int count) => Produce(count);
+
+    /// <inheritdoc />
+    Memory<byte> IBufferWriter<byte>.GetMemory(int sizeHint)
+    {
+        ArgumentOutOfRangeException.ThrowIfNegative(sizeHint);
+
+        var result = Buffer;
+        return sizeHint <= result.Length ? result : throw new InsufficientMemoryException();
+    }
+
+    /// <inheritdoc />
+    Span<byte> IBufferWriter<byte>.GetSpan(int sizeHint)
+    {
+        ArgumentOutOfRangeException.ThrowIfNegative(sizeHint);
+
+        var result = Buffer.Span;
+        return sizeHint <= result.Length ? result : throw new InsufficientMemoryException();
+    }
+}

src/DotNext.IO/IO/FileReader.cs

@@ -13,7 +13,7 @@ namespace DotNext.IO;
 /// This class is not thread-safe. However, it's possible to share the same file
 /// handle across multiple readers and use dedicated reader in each thread.
 /// </remarks>
-public partial class FileReader : Disposable, IResettable
+public partial class FileReader : Disposable, IBufferedReader
 {
     private const int MinBufferSize = 16;
     private const int DefaultBufferSize = 4096;
@@ -55,9 +55,7 @@ public FileReader(FileStream source)
         FilePosition = source.Position;
     }
 
-    /// <summary>
-    /// Gets or sets the buffer allocator.
-    /// </summary>
+    /// <inheritdoc cref="IBufferedChannel.Allocator"/>
     public MemoryAllocator<byte>? Allocator
     {
         get;
@@ -95,9 +93,7 @@ public long FilePosition
     [DebuggerBrowsable(DebuggerBrowsableState.Never)]
     private int BufferLength => bufferEnd - bufferStart;
 
-    /// <summary>
-    /// Gets unconsumed part of the buffer.
-    /// </summary>
+    /// <inheritdoc cref="IBufferedReader.Buffer"/>
     public ReadOnlyMemory<byte> Buffer => buffer.Memory[bufferStart..bufferEnd];
 
     [DebuggerBrowsable(DebuggerBrowsableState.Never)]
@@ -118,21 +114,14 @@ private ref readonly MemoryOwner<byte> EnsureBufferAllocated()
     /// </summary>
     public bool HasBufferedData => bufferStart < bufferEnd;
 
-    /// <summary>
-    /// Gets the maximum possible amount of data that can be placed to the buffer.
-    /// </summary>
-    /// <exception cref="ArgumentOutOfRangeException"><paramref name="value"/> too small.</exception>
+    /// <inheritdoc cref="IBufferedChannel.MaxBufferSize"/>
     public int MaxBufferSize
     {
         get => maxBufferSize;
         init => maxBufferSize = value >= MinBufferSize ? value : throw new ArgumentOutOfRangeException(nameof(value));
     }
 
-    /// <summary>
-    /// Advances read position.
-    /// </summary>
-    /// <param name="count">The number of consumed bytes.</param>
-    /// <exception cref="ArgumentOutOfRangeException"><paramref name="count"/> is larger than the length of <see cref="Buffer"/>.</exception>
+    /// <inheritdoc cref="IBufferedReader.Consume(int)"/>
     public void Consume(int count)
     {
         ObjectDisposedException.ThrowIf(IsDisposed, this);
@@ -200,17 +189,7 @@ public void Reset()
         buffer.Dispose();
     }
 
-    /// <summary>
-    /// Reads the data from the file to the underlying buffer.
-    /// </summary>
-    /// <param name="token">The token that can be used to cancel the operation.</param>
-    /// <returns>
-    /// <see langword="true"/> if the data has been copied from the file to the internal buffer;
-    /// <see langword="false"/> if no more data to read.
-    /// </returns>
-    /// <exception cref="ObjectDisposedException">The reader has been disposed.</exception>
-    /// <exception cref="InternalBufferOverflowException">Internal buffer has no free space.</exception>
-    /// <exception cref="OperationCanceledException">The operation has been canceled.</exception>
+    /// <inheritdoc cref="IBufferedReader.ReadAsync(CancellationToken)"/>
     public ValueTask<bool> ReadAsync(CancellationToken token = default)
     {
         return IsDisposed
@@ -283,14 +262,7 @@ private bool ReadCore()
         return count > 0;
     }
 
-    /// <summary>
-    /// Reads the block of the memory.
-    /// </summary>
-    /// <param name="destination">The output buffer.</param>
-    /// <param name="token">The token that can be used to cancel the operation.</param>
-    /// <returns>The number of bytes copied to <paramref name="destination"/>.</returns>
-    /// <exception cref="ObjectDisposedException">The reader has been disposed.</exception>
-    /// <exception cref="OperationCanceledException">The operation has been canceled.</exception>
+    /// <inheritdoc cref="IBufferedReader.ReadAsync(Memory{byte}, CancellationToken)"/>
     public ValueTask<int> ReadAsync(Memory<byte> destination, CancellationToken token = default)
     {
         ValueTask<int> task;

src/DotNext.IO/IO/FileWriter.BufferWriter.cs

@@ -12,7 +12,7 @@ namespace DotNext.IO;
 /// This class is not thread-safe. However, it's possible to share the same file
 /// handle across multiple writers and use dedicated writer in each thread.
 /// </remarks>
-public partial class FileWriter : Disposable, IFlushable, IResettable
+public partial class FileWriter : Disposable, IFlushable, IBufferedWriter
 {
     private const int MinBufferSize = 16;
     private const int DefaultBufferSize = 4096;
@@ -53,9 +53,7 @@ public FileWriter(FileStream destination)
         FilePosition = destination.Position;
     }
 
-    /// <summary>
-    /// Gets or sets the buffer allocator.
-    /// </summary>
+    /// <inheritdoc cref="IBufferedChannel.Allocator"/>
     public MemoryAllocator<byte>? Allocator
     {
         get;
@@ -96,21 +94,14 @@ private void AssertState()
     [DebuggerBrowsable(DebuggerBrowsableState.Never)]
     private Span<byte> BufferSpan => EnsureBufferAllocated().Span.Slice(bufferOffset);
 
-    /// <summary>
-    /// Gets the maximum available buffer size.
-    /// </summary>
-    /// <exception cref="ArgumentOutOfRangeException"><paramref name="value"/> too small.</exception>
+    /// <inheritdoc cref="IBufferedChannel.MaxBufferSize"/>
     public int MaxBufferSize
     {
         get => maxBufferSize;
         init => maxBufferSize = value >= MinBufferSize ? value : throw new ArgumentOutOfRangeException(nameof(value));
     }
 
-    /// <summary>
-    /// Marks the specified number of bytes in the buffer as produced.
-    /// </summary>
-    /// <param name="count">The number of produced bytes.</param>
-    /// <exception cref="ArgumentOutOfRangeException"><paramref name="count"/> is larger than the length of <see cref="Buffer"/>.</exception>
+    /// <inheritdoc cref="IBufferedWriter.Produce(int)"/>
     public void Produce(int count)
     {
         ObjectDisposedException.ThrowIf(IsDisposed, this);
@@ -169,7 +160,7 @@ public bool HasBufferedData
     /// Gets or sets the cursor position within the file.
     /// </summary>
     /// <exception cref="ArgumentOutOfRangeException">The value is less than zero.</exception>
-    /// <exception cref="InvalidOperationException">There is buffered data present. Call <see cref="ClearBuffer"/> or <see cref="WriteAsync(CancellationToken)"/> before changing the position.</exception>
+    /// <exception cref="InvalidOperationException">There is buffered data present. Call <see cref="Reset()"/> or <see cref="WriteAsync(CancellationToken)"/> before changing the position.</exception>
     public long FilePosition
     {
         get => fileOffset;
@@ -203,13 +194,7 @@ private void Flush()
         Reset();
     }
 
-    /// <summary>
-    /// Flushes buffered data to the file.
-    /// </summary>
-    /// <param name="token">The token that can be used to cancel the operation.</param>
-    /// <returns>The task representing asynchronous result.</returns>
-    /// <exception cref="ObjectDisposedException">The writer has been disposed.</exception>
-    /// <exception cref="OperationCanceledException">The operation has been canceled.</exception>
+    /// <inheritdoc cref="IBufferedWriter.WriteAsync(CancellationToken)"/>
     public ValueTask WriteAsync(CancellationToken token = default)
     {
         if (IsDisposed)
@@ -272,14 +257,7 @@ private void WriteSlow(ReadOnlySpan<byte> input)
         }
     }
 
-    /// <summary>
-    /// Writes the data to the file through the buffer.
-    /// </summary>
-    /// <param name="input">The input data to write.</param>
-    /// <param name="token">The token that can be used to cancel the operation.</param>
-    /// <returns>The task representing asynchronous result.</returns>
-    /// <exception cref="ObjectDisposedException">The object has been disposed.</exception>
-    /// <exception cref="OperationCanceledException">The operation has been canceled.</exception>
+    /// <inheritdoc cref="IBufferedWriter.WriteAsync(ReadOnlyMemory{byte}, CancellationToken)"/>
     public ValueTask WriteAsync(ReadOnlyMemory<byte> input, CancellationToken token = default)
     {
         ValueTask task;