benchmark md updates

ReadOnlyMemory Interface for testing

Author: Hirogen

src/LogExpert.Core/Classes/Log/LogStreamReaderBase.cs

@@ -1,4 +1,3 @@
-using System;
 using System.Text;
 
 using LogExpert.Core.Interface;
@@ -9,12 +8,12 @@ public abstract class LogStreamReaderBase : ILogStreamReader
 {
     #region cTor
 
-    protected LogStreamReaderBase()
+    protected LogStreamReaderBase ()
     {
 
     }
 
-    ~LogStreamReaderBase()
+    ~LogStreamReaderBase ()
     {
         Dispose(false);
     }
@@ -44,7 +43,7 @@ protected LogStreamReaderBase()
     /// <summary>
     /// Destroy and release the current stream reader.
     /// </summary>
-    public void Dispose()
+    public void Dispose ()
     {
         Dispose(true);
         GC.SuppressFinalize(this);
@@ -53,11 +52,11 @@ public void Dispose()
     /// Destroy and release the current stream reader.
     /// </summary>
     /// <param name="disposing">Specifies whether or not the managed objects should be released.</param>
-    protected abstract void Dispose(bool disposing);
+    protected abstract void Dispose (bool disposing);
 
-    public abstract int ReadChar();
+    public abstract int ReadChar ();
 
-    public abstract string ReadLine();
+    public abstract string ReadLine ();
 
     #endregion
 }

src/LogExpert.Core/Classes/Log/PositionAwareStreamReaderPipeline.cs

@@ -4,10 +4,11 @@
 using System.Text;
 
 using LogExpert.Core.Entities;
+using LogExpert.Core.Interface;
 
 namespace LogExpert.Core.Classes.Log;
 
-public class PositionAwareStreamReaderPipeline : LogStreamReaderBase
+public class PositionAwareStreamReaderPipeline : LogStreamReaderBase, ILogStreamReaderSpan
 {
     private const int DEFAULT_BYTE_BUFFER_SIZE = 64 * 1024; // 64 KB
     private const int MINIMUM_READ_AHEAD_SIZE = 4 * 1024; // 4 KB
@@ -30,6 +31,8 @@ public class PositionAwareStreamReaderPipeline : LogStreamReaderBase
     private readonly int _charBufferSize;
     private readonly long _preambleLength;
 
+    private LineSegment? _currentSegment;
+
     private PipeReader _pipeReader;
     private CancellationTokenSource _cts;
     private Task _producerTask;
@@ -99,42 +102,49 @@ public override int ReadChar ()
 
     public override string ReadLine ()
     {
-        ObjectDisposedException.ThrowIf(IsDisposed, GetType());
-
-        // Check for producer exception
-        var producerEx = Volatile.Read(ref _producerException);
-        if (producerEx != null)
-        {
-            throw new InvalidOperationException("Producer task encountered an error.", producerEx);
-        }
-
-        LineSegment segment;
-        try
-        {
-            // BlockingCollection.Take() blocks until an item is available or collection is completed
-            // This eliminates the race condition present in the semaphore + queue approach
-            segment = _lineQueue.Take(_cts?.Token ?? CancellationToken.None);
-        }
-        catch (OperationCanceledException)
-        {
-            return null;
-        }
-        catch (InvalidOperationException) // Thrown when collection is marked as completed and empty
-        {
-            return null;
-        }
-
-        using (segment)
-        {
-            if (segment.IsEof)
-            {
-                return null;
-            }
-
-            var line = new string(segment.Buffer, 0, segment.Length);
-            _ = Interlocked.Exchange(ref _position, segment.ByteOffset + segment.ByteLength);
-            return line;
-        }
+        if (TryReadLine(out var lineMemory))
+        {
+            return new string(lineMemory.Span); // Only allocate when explicitly requested
+        }
+
+        return null;
+
+        //ObjectDisposedException.ThrowIf(IsDisposed, GetType());
+
+        //// Check for producer exception
+        //var producerEx = Volatile.Read(ref _producerException);
+        //if (producerEx != null)
+        //{
+        //    throw new InvalidOperationException("Producer task encountered an error.", producerEx);
+        //}
+
+        //LineSegment segment;
+        //try
+        //{
+        //    // BlockingCollection.Take() blocks until an item is available or collection is completed
+        //    // This eliminates the race condition present in the semaphore + queue approach
+        //    segment = _lineQueue.Take(_cts?.Token ?? CancellationToken.None);
+        //}
+        //catch (OperationCanceledException)
+        //{
+        //    return null;
+        //}
+        //catch (InvalidOperationException) // Thrown when collection is marked as completed and empty
+        //{
+        //    return null;
+        //}
+
+        //using (segment)
+        //{
+        //    if (segment.IsEof)
+        //    {
+        //        return null;
+        //    }
+
+        //    var line = new string(segment.Buffer, 0, segment.Length);
+        //    _ = Interlocked.Exchange(ref _position, segment.ByteOffset + segment.ByteLength);
+        //    return line;
+        //}
     }
 
     protected override void Dispose (bool disposing)
@@ -621,6 +631,42 @@ private static (int length, Encoding? detectedEncoding) DetectPreambleLength (St
         return (0, null);
     }
 
+    public bool TryReadLine (out ReadOnlyMemory<char> lineMemory)
+    {
+        ObjectDisposedException.ThrowIf(IsDisposed, GetType());
+
+        var producerEx = Volatile.Read(ref _producerException);
+        if (producerEx != null)
+        {
+            throw new InvalidOperationException("Producer task encountered an error.", producerEx);
+        }
+
+        if (!_lineQueue.TryTake(out var segment, 100, _cts?.Token ?? CancellationToken.None))
+        {
+            lineMemory = default;
+            return false;
+        }
+
+        // Store segment for lifetime management
+        _currentSegment?.Dispose();
+        _currentSegment = segment;
+
+        if (segment.IsEof)
+        {
+            lineMemory = default;
+            return false;
+        }
+
+        lineMemory = new ReadOnlyMemory<char>(segment.Buffer, 0, segment.Length);
+        _ = Interlocked.Exchange(ref _position, segment.ByteOffset + segment.ByteLength);
+        return true;
+    }
+
+    public void ReturnMemory (ReadOnlyMemory<char> memory)
+    {
+        throw new NotImplementedException();
+    }
+
     /// <summary>
     /// Represents a line segment with its position and metadata.
     /// Uses ArrayPool for efficient char buffer management.

src/LogExpert.Core/Interface/ILogStreamReader.cs

@@ -2,22 +2,154 @@
 
 namespace LogExpert.Core.Interface;
 
+/// <summary>
+/// Provides a position-aware stream reader interface for reading log files with support for character encoding
+/// and position tracking.
+/// </summary>
+/// <remarks>
+/// <para>
+/// This interface abstracts log file reading operations, providing a consistent API for different stream reading
+/// implementations. All implementations must maintain accurate byte position tracking to support seeking and
+/// re-reading specific portions of the log file.
+/// </para>
+/// <para>
+/// Implementations include:
+/// <list type="bullet">
+/// <item><description><c>PositionAwareStreamReaderLegacy</c> - Character-by-character reading for precise position control</description></item>
+/// <item><description><c>PositionAwareStreamReaderSystem</c> - Uses .NET's StreamReader.ReadLine() for improved performance</description></item>
+/// <item><description><c>PositionAwareStreamReaderPipeline</c> - Modern async pipeline-based implementation using System.IO.Pipelines</description></item>
+/// <item><description><c>XmlLogReader</c> - Decorator for reading structured XML log blocks (e.g., Log4j XML format)</description></item>
+/// </list>
+/// </para>
+/// </remarks>
 public interface ILogStreamReader : IDisposable
 {
     #region Properties
 
+    /// <summary>
+    /// Gets or sets the current byte position in the stream.
+    /// </summary>
+    /// <value>
+    /// The zero-based byte offset from the beginning of the stream, accounting for any byte order mark (BOM).
+    /// </value>
+    /// <remarks>
+    /// <para>
+    /// Setting the position causes the reader to seek to the specified byte offset in the underlying stream.
+    /// This operation may be expensive as it requires resetting internal buffers and decoder state.
+    /// </para>
+    /// <para>
+    /// The position should always represent a valid character boundary. Setting the position to the middle
+    /// of a multi-byte character may result in decoding errors or incorrect output.
+    /// </para>
+    /// <para>
+    /// After seeking, the next <see cref="ReadLine"/> or <see cref="ReadChar"/> operation will begin reading
+    /// from the new position.
+    /// </para>
+    /// </remarks>
     long Position { get; set; }
 
+    /// <summary>
+    /// Gets a value indicating whether the internal buffer has been completely filled from the stream.
+    /// </summary>
+    /// <value>
+    /// <see langword="true"/> if the buffer is complete and no additional data needs to be loaded;
+    /// otherwise, <see langword="false"/>.
+    /// </value>
+    /// <remarks>
+    /// This property is primarily used to determine if the reader is still waiting for data to become
+    /// available in the stream. Most implementations return <see langword="true"/> as they read directly
+    /// from the stream without pre-buffering.
+    /// </remarks>
     bool IsBufferComplete { get; }
 
+    /// <summary>
+    /// Gets the character encoding used by the stream reader.
+    /// </summary>
+    /// <value>
+    /// The <see cref="System.Text.Encoding"/> object representing the character encoding of the stream.
+    /// </value>
+    /// <remarks>
+    /// <para>
+    /// The encoding is determined during initialization and may be detected from a byte order mark (BOM)
+    /// at the beginning of the stream, explicitly specified via <c>EncodingOptions</c>, or defaulted to
+    /// the system default encoding.
+    /// </para>
+    /// <para>
+    /// Supported BOM detection includes:
+    /// <list type="bullet">
+    /// <item><description>UTF-8 (EF BB BF)</description></item>
+    /// <item><description>UTF-16 Little Endian (FF FE)</description></item>
+    /// <item><description>UTF-16 Big Endian (FE FF)</description></item>
+    /// <item><description>UTF-32 Little Endian (FF FE 00 00)</description></item>
+    /// <item><description>UTF-32 Big Endian (00 00 FE FF)</description></item>
+    /// </list>
+    /// </para>
+    /// </remarks>
     Encoding Encoding { get; }
 
     #endregion
 
     #region Public methods
 
+    /// <summary>
+    /// Reads the next character from the stream and advances the position by the number of bytes consumed.
+    /// </summary>
+    /// <returns>
+    /// The next character as an <see cref="int"/>, or -1 if the end of the stream has been reached.
+    /// </returns>
+    /// <remarks>
+    /// <para>
+    /// The return value is an <see cref="int"/> rather than a <see cref="char"/> to allow returning -1
+    /// for end-of-stream, following the convention established by <see cref="StreamReader.Read()"/>.
+    /// </para>
+    /// <para>
+    /// After reading a character, the <see cref="Position"/> property is automatically advanced by the
+    /// number of bytes consumed from the stream. For single-byte encodings this is always 1, for UTF-16
+    /// this is always 2, but for variable-width encodings like UTF-8 this may be 1-4 bytes depending on
+    /// the character.
+    /// </para>
+    /// <para>
+    /// Some implementations (like <c>PositionAwareStreamReaderPipeline</c>) may not support this method
+    /// and will throw <see cref="NotSupportedException"/> as they are optimized for line-based reading only.
+    /// </para>
+    /// </remarks>
+    /// <exception cref="ObjectDisposedException">The reader has been disposed.</exception>
+    /// <exception cref="NotSupportedException">The implementation does not support character-level reading.</exception>
+    /// <exception cref="IOException">An I/O error occurred while reading from the stream.</exception>
     int ReadChar ();
 
+    /// <summary>
+    /// Reads a line of characters from the stream and advances the position by the number of bytes consumed.
+    /// </summary>
+    /// <returns>
+    /// A string containing the next line from the stream (excluding newline characters), or <see langword="null"/>
+    /// if the end of the stream has been reached.
+    /// </returns>
+    /// <remarks>
+    /// <para>
+    /// A line is defined as a sequence of characters followed by a line feed (\n), a carriage return (\r),
+    /// or a carriage return followed by a line feed (\r\n). The returned string does not include the
+    /// terminating newline character(s).
+    /// </para>
+    /// <para>
+    /// The <see cref="Position"/> property is automatically advanced by the total number of bytes consumed,
+    /// including the newline character(s).
+    /// </para>
+    /// <para>
+    /// Implementations may enforce a maximum line length constraint. Lines exceeding this limit will be
+    /// truncated to the maximum length. The specific limit is implementation-dependent and typically
+    /// specified during construction.
+    /// </para>
+    /// <para>
+    /// If the stream ends without a trailing newline, the remaining characters are returned as the last line.
+    /// Subsequent calls will return <see langword="null"/> to indicate end-of-stream.
+    /// </para>
+    /// </remarks>
+    /// <exception cref="ObjectDisposedException">The reader has been disposed.</exception>
+    /// <exception cref="IOException">An I/O error occurred while reading from the stream.</exception>
+    /// <exception cref="InvalidOperationException">
+    /// The internal producer task encountered an error (specific to async implementations).
+    /// </exception>
     string ReadLine ();
 
     #endregion

src/LogExpert.Core/Interface/ISpanLineReader.cs

@@ -0,0 +1,8 @@
+namespace LogExpert.Core.Interface;
+
+public interface ISpanLineReader
+{
+    bool TryReadLine (out ReadOnlySpan<char> line);
+
+    long Position { get; }
+}

src/LogExpert.sln

@@ -98,6 +98,11 @@ Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "LogExpert.Persister.Tests",
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "LogExpert.Benchmarks", "LogExpert.Benchmarks\LogExpert.Benchmarks.csproj", "{1046779B-500D-8260-33BA-BC778C4B836F}"
 EndProject
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "performance", "performance", "{C83F15B6-F6E0-4526-A5C5-47806772E49A}"
+	ProjectSection(SolutionItems) = preProject
+		docs\performance\BENCHMARK_SUMMARY.md = docs\performance\BENCHMARK_SUMMARY.md
+	EndProjectSection
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -230,6 +235,7 @@ Global
 		{39822C1B-E4C6-40F3-86C4-74C68BDEF3D0} = {DE6375A4-B4C4-4620-8FFB-B9D5A4E21144}
 		{CAD17410-CE8C-4FE5-91DE-1B3DE2945135} = {848C24BA-BEBA-48EC-90E6-526ECAB6BB4A}
 		{1046779B-500D-8260-33BA-BC778C4B836F} = {848C24BA-BEBA-48EC-90E6-526ECAB6BB4A}
+		{C83F15B6-F6E0-4526-A5C5-47806772E49A} = {39822C1B-E4C6-40F3-86C4-74C68BDEF3D0}
 	EndGlobalSection
 	GlobalSection(ExtensibilityGlobals) = postSolution
 		SolutionGuid = {15924D5F-B90B-4BC7-9E7D-BCCB62EBABAD}