Add FileOpenMode option

Author: neuecc

README.md

@@ -86,31 +86,6 @@ The `ReadOnlyMemory<byte>` returned from `ReadLineAsync` or `TryReadLine` is onl
 
 This design is similar to [System.IO.Pipelines](https://learn.microsoft.com/en-us/dotnet/standard/io/pipelines).
 
-## Optimizing FileStream
-
-Similar to `StreamReader`, `Utf8StreamReader` has the ability to open a `FileStream` by accepting a `string path`.
-
-```csharp
-public Utf8StreamReader(string path)
-public Utf8StreamReader(string path, int bufferSize)
-public Utf8StreamReader(string path, FileStreamOptions options)
-public Utf8StreamReader(string path, FileStreamOptions options, int bufferSize)
-```
-
-Unfortunately, the `FileStream` used by `StreamReader` is not optimized for modern .NET. For example, when using `FileStream` with asynchronous methods, it should be opened with `useAsync: true` for optimal performance. However, since `StreamReader` has both synchronous and asynchronous methods in its API, false is specified. Additionally, although `StreamReader` itself has a buffer and `FileStream` does not require a buffer, the buffer of `FileStream` is still being utilized.
-
-Strictly speaking, [FileStream underwent a major overhaul in .NET 6](https://github.com/dotnet/runtime/issues/40359). The behavior is controlled by an internal `FileStreamStrategy`. For instance, on Windows, `SyncWindowsFileStreamStrategy` is used when useAsync is false, and `AsyncWindowsFileStreamStrategy` is used when useAsync is true. Moreover, if bufferSize is set to 1, the `FileStreamStrategy` is used directly, and it writes directly to the buffer passed via `ReadAsync(Memory<byte>)`. If any other value is specified, it is wrapped in a `BufferedFileStreamStrategy`.
-
-Based on these observations of the internal behavior, `Utf8StreamReader` generates a `FileStream` with the following options:
-
-```csharp
-new FileStream(path, FileMode.Open, FileAccess.Read, FileShare.Read, bufferSize: 1, useAsync: true)
-```
-
-Furthermore, by devising how to call Stream as a whole, we have succeeded in making it function as a thin wrapper for [RandomAccess.ReadAsync](https://learn.microsoft.com/en-us/dotnet/api/system.io.randomaccess.readasync), which is the fastest way to call it.
-
-For overloads that accept `FileStreamOptions`, the above settings are not reflected, so please adjust them manually.
-
 ## Read as `ReadOnlyMemory<char>`
 
 You can convert it to a `Utf8TextReader` that extracts `ReadOnlyMemory<char>` or `string`. Although there is a conversion cost, it is still fast and low allocation, so it can be used as an alternative to `StreamReader`.
@@ -137,6 +112,58 @@ You can perform text processing without allocation, such as splitting `ReadOnlyS
 
 When a string is needed, you can convert `ReadOnlyMemory<char>` to a string using `ToString()`. Even with the added string conversion, the performance is higher than `StreamReader`, so it can be used as a better alternative.
 
+## Optimizing FileStream
+
+Similar to `StreamReader`, `Utf8StreamReader` has the ability to open a `FileStream` by accepting a `string path`.
+
+```csharp
+public Utf8StreamReader(string path, FileOpenMode fileOpenMode = FileOpenMode.Scalability)
+public Utf8StreamReader(string path, int bufferSize, FileOpenMode fileOpenMode = FileOpenMode.Scalability)
+public Utf8StreamReader(string path, FileStreamOptions options)
+public Utf8StreamReader(string path, FileStreamOptions options, int bufferSize)
+```
+
+Unfortunately, the `FileStream` used by `StreamReader` is not optimized for modern .NET. For example, when using `FileStream` with asynchronous methods, it should be opened with `useAsync: true` for optimal performance. However, since `StreamReader` has both synchronous and asynchronous methods in its API, false is specified. Additionally, although `StreamReader` itself has a buffer and `FileStream` does not require a buffer, the buffer of `FileStream` is still being utilized.
+
+It is difficult to handle `FileStream` correctly with high performance. By specifying a `string path`, the stream is opened with options optimized for `Utf8StreamReader`, so it is recommended to use this overload rather than opening `FileStream` yourself. The following is a benchmark of `FileStream`.
+
+![image](https://github.com/Cysharp/Utf8StreamReader/assets/46207/83936827-2380-414a-9778-f53252689eb7)
+
+`Utf8StreamReader` opens `FileStream` with the following settings:
+
+```csharp
+var useAsync = (fileOpenMode == FileOpenMode.Scalability);
+new FileStream(path, FileMode.Open, FileAccess.Read, FileShare.Read, bufferSize: 1, useAsync: useAsync)
+```
+
+Due to historical reasons, the options for `FileStream` are odd, but by setting `bufferSize` to 1, you can avoid the use of internal buffers. `FileStream` has been significantly revamped in .NET 6, and by controlling the setting of this option and the way `Utf8StreamReader` is called as a whole, it can function as a thin wrapper around the fast [RandomAccess.ReadAsync](https://learn.microsoft.com/en-us/dotnet/api/system.io.randomaccess.readasync), allowing you to avoid most of the overhead of FileStream.
+
+`FileOpenMode` is a proprietary option of `Utf8StreamReader`.
+
+
+```csharp
+public enum FileOpenMode
+{
+    Scalability,
+    Throughput
+}
+```
+
+In a Windows environment, the table in the [IO section of the Performance Improvements in .NET 6 blog](https://devblogs.microsoft.com/dotnet/performance-improvements-in-net-6/#io) shows that throughput decreases when `useAsync: true` is used.
+
+| Method | Runtime | IsAsync | BufferSize | Mean |
+| -      | -       | -       | -          | -    |
+| ReadAsync	| .NET 6.0 | True | 1 | 119.573 ms |
+| ReadAsync	| .NET 6.0 | False | 1 | 36.018 ms |
+
+By setting `Utf8StreamReader` to `FileOpenMode.Scalability`, true async I/O is enabled and scalability is prioritized. If set to `FileOpenMode.Throughput`, it internally becomes sync-over-async and consumes the ThreadPool, but reduces the overhead of asynchronous I/O and improves throughput.
+
+If frequently executed within a server application, setting it to `Scalability`, and for batch applications, setting it to `Throughput` will likely yield the best performance characteristics. The default is `Scalability`.
+
+In `Utf8StreamReader`, by carefully adjusting the buffer size on the `Utf8StreamReader` side, the performance difference is minimized. Please refer to the above benchmark results image for specific values.
+
+For overloads that accept `FileStreamOptions`, the above settings are not reflected, so please adjust them manually.
+
 ## Reset
 
 `Utf8StreamReader` is a class that supports reuse. By calling `Reset()`, the Stream and internal state are released. Using `Reset(Stream)`, it can be reused with a new `Stream`.
@@ -145,7 +172,7 @@ When a string is needed, you can convert `ReadOnlyMemory<char>` to a string usin
 
 The constructor accepts `int bufferSize` and `bool leaveOpen` as parameters.
 
-`int bufferSize` defaults to 4096, but if the data per line is large, changing the buffer size may improve performance. When the buffer size and the size per line are close, frequent buffer copy operations occur, leading to performance degradation.
+`int bufferSize` defaults to 65536 and the buffer is rented from `ArrayPool<byte>`. If the data per line is large, changing the buffer size may improve performance. When the buffer size and the size per line are close, frequent buffer copy operations occur, leading to performance degradation.
 
 `bool leaveOpen` determines whether the internal Stream is also disposed when the object is disposed. The default is `false`, which means the Stream is disposed.
 

sandbox/Benchmark/FromFile.cs

@@ -1,9 +1,8 @@
-using System.Text;
+using BenchmarkDotNet.Attributes;
+using Cysharp.IO;
 using System.Text.Encodings.Web;
 using System.Text.Json;
 using System.Text.Unicode;
-using BenchmarkDotNet.Attributes;
-using Cysharp.IO;
 
 namespace Benchmark;
 
@@ -43,52 +42,90 @@ public void GlobalCleanup()
     }
 
     [Benchmark]
-    public async Task StreamReader()
+    public async Task StreamReaderFileStream()
     {
-        using var fs = File.OpenRead(filePath);
-        using var sr = new System.IO.StreamReader(fs);
+        using var sr = new System.IO.StreamReader(filePath);
         string? line;
         while ((line = await sr.ReadLineAsync()) != null)
         {
-            // Console.WriteLine(line);
+            // ...
+        }
+    }
+
+    [Benchmark]
+    public async Task Utf8StreamReaderFileStreamScalability()
+    {
+        using var sr = new Cysharp.IO.Utf8StreamReader(filePath, fileOpenMode: FileOpenMode.Scalability);
+        while (await sr.LoadIntoBufferAsync())
+        {
+            while (sr.TryReadLine(out var line))
+            {
+                // ...
+            }
+        }
+    }
+
+    [Benchmark]
+    public async Task Utf8StreamReaderFileStreamThroughput()
+    {
+        using var sr = new Cysharp.IO.Utf8StreamReader(filePath, fileOpenMode: FileOpenMode.Throughput);
+        while (await sr.LoadIntoBufferAsync())
+        {
+            while (sr.TryReadLine(out var line))
+            {
+                // ...
+            }
+        }
+    }
+
+    [Benchmark]
+    public async Task Utf8TextReaderFileStreamScalability()
+    {
+        using var sr = new Cysharp.IO.Utf8StreamReader(filePath, fileOpenMode: FileOpenMode.Scalability).AsTextReader();
+        while (await sr.LoadIntoBufferAsync())
+        {
+            while (sr.TryReadLine(out var line))
+            {
+                // ...
+            }
         }
     }
 
     [Benchmark]
-    public async Task Utf8StreamReader()
+    public async Task Utf8TextReaderFileStreamThroughput()
     {
-        using var sr = new Cysharp.IO.Utf8StreamReader(filePath);
+        using var sr = new Cysharp.IO.Utf8StreamReader(filePath, fileOpenMode: FileOpenMode.Throughput).AsTextReader();
         while (await sr.LoadIntoBufferAsync())
         {
             while (sr.TryReadLine(out var line))
             {
-                // Console.WriteLine(Encoding.UTF8.GetString( line.Span));
+                // ...
             }
         }
     }
 
     [Benchmark]
-    public async Task Utf8TextReader()
+    public async Task Utf8TextReaderToStringFileStreamScalability()
     {
-        using var sr = new Cysharp.IO.Utf8StreamReader(filePath).AsTextReader();
+        using var sr = new Cysharp.IO.Utf8StreamReader(filePath, fileOpenMode: FileOpenMode.Scalability).AsTextReader();
         while (await sr.LoadIntoBufferAsync())
         {
             while (sr.TryReadLine(out var line))
             {
-                // Console.WriteLine(line);
+                _ = line.ToString();
             }
         }
     }
 
     [Benchmark]
-    public async Task Utf8TextReaderToString()
+    public async Task Utf8TextReaderToStringFileStreamThroughput()
     {
-        using var sr = new Cysharp.IO.Utf8StreamReader(filePath).AsTextReader();
+        using var sr = new Cysharp.IO.Utf8StreamReader(filePath, fileOpenMode: FileOpenMode.Throughput).AsTextReader();
         while (await sr.LoadIntoBufferAsync())
         {
             while (sr.TryReadLine(out var line))
             {
-                // Console.WriteLine(line);
+                _ = line.ToString();
             }
         }
     }

sandbox/Benchmark/FromMemory.cs

@@ -1,5 +1,4 @@
-
-using System.Buffers;
+using System.Buffers;
 using System.IO.Pipelines;
 using System.Text;
 using System.Text.Encodings.Web;

src/Utf8StreamReader/Utf8StreamReader.cs

@@ -4,12 +4,18 @@
 
 namespace Cysharp.IO;
 
+public enum FileOpenMode
+{
+    Scalability,
+    Throughput
+}
+
 public sealed class Utf8StreamReader : IAsyncDisposable, IDisposable
 {
     // NetStandard2.1 does not have Array.MaxLength so use constant.
     const int ArrayMaxLength = 0X7FFFFFC7;
 
-    const int DefaultBufferSize = 4096;
+    const int DefaultBufferSize = 65536;
     const int MinBufferSize = 1024;
 
     Stream stream;
@@ -56,21 +62,24 @@ public Utf8StreamReader(Stream stream, int bufferSize, bool leaveOpen)
         this.leaveOpen = leaveOpen;
     }
 
-    public Utf8StreamReader(string path)
-      : this(path, DefaultBufferSize)
+    public Utf8StreamReader(string path, FileOpenMode fileOpenMode = FileOpenMode.Scalability)
+      : this(path, DefaultBufferSize, fileOpenMode)
     {
     }
 
-    public Utf8StreamReader(string path, int bufferSize)
-        : this(OpenPath(path), bufferSize, leaveOpen: false)
+    public Utf8StreamReader(string path, int bufferSize, FileOpenMode fileOpenMode = FileOpenMode.Scalability)
+        : this(OpenPath(path, fileOpenMode), bufferSize, leaveOpen: false)
     {
     }
 
-    static FileStream OpenPath(string path)
+    static FileStream OpenPath(string path, FileOpenMode fileOpenMode = FileOpenMode.Scalability)
     {
         // useAsync:1 + bufferSize 1 chooses internal FileStreamStrategy to AsyncWindowsFileStreamStrategy(in windows)
         // but bufferSize larger than 1, wrapped strategy with BufferedFileStreamStrategy, it is unnecessary in ReadLine.
-        return new FileStream(path, FileMode.Open, FileAccess.Read, FileShare.Read, bufferSize: 1, useAsync: true);
+        var fileOptions = (fileOpenMode == FileOpenMode.Scalability)
+            ? (FileOptions.SequentialScan | FileOptions.Asynchronous)
+            : FileOptions.SequentialScan;
+        return new FileStream(path, FileMode.Open, FileAccess.Read, FileShare.Read, bufferSize: 1, options: fileOptions);
     }
 
 #if !NETSTANDARD

src/Utf8StreamReader/Utf8TextReader.cs

@@ -6,8 +6,8 @@ namespace Cysharp.IO;
 
 public sealed class Utf8TextReader : IDisposable, IAsyncDisposable
 {
-    const int DefaultCharBufferSize = 4096;
-    const int MinBufferSize = 1024;
+    const int DefaultCharBufferSize = 1024; // buffer per line.
+    const int MinBufferSize = 128;
 
     readonly Utf8StreamReader reader;
     readonly int bufferSize;