refactor: move buffer allocation to encoder with ArrayPool threshold, PolylineWriter accepts external char[]

Agent-Logs-Url: https://github.com/petesramek/polyline-algorithm-csharp/sessions/08c12b26-d5d8-4708-a74b-78e4cf6e2cbb

Co-authored-by: petesramek <2333452+petesramek@users.noreply.github.com>

Author: Copilot

src/PolylineAlgorithm/Abstraction/AbstractPolylineEncoder.cs

@@ -10,6 +10,7 @@ namespace PolylineAlgorithm.Abstraction;
 using PolylineAlgorithm.Internal;
 using PolylineAlgorithm.Internal.Diagnostics;
 using System;
+using System.Buffers;
 using System.Diagnostics;
 using System.Runtime.CompilerServices;
 using System.Threading;
@@ -88,7 +89,16 @@ public TPolyline Encode(ReadOnlySpan<TCoordinate> coordinates, CancellationToken
 
         // Worst-case maximum: every value uses the maximum number of encoded characters.
         int maxCapacity = coordinates.Length * 2 * Defaults.Polyline.Block.Length.Max;
-        PolylineWriter writer = new(maxCapacity, Options.Precision);
+
+        // Use ArrayPool for large buffers to avoid large heap allocations; for small buffers a fresh
+        // allocation is cheaper than pool overhead.
+        const int StackAllocThreshold = 512;
+        char[]? rentedBuffer = maxCapacity > StackAllocThreshold
+            ? ArrayPool<char>.Shared.Rent(maxCapacity)
+            : null;
+        char[] buffer = rentedBuffer ?? new char[maxCapacity];
+
+        PolylineWriter writer = new(buffer, Options.Precision);
 
         TPolyline result;
 
@@ -102,7 +112,9 @@ public TPolyline Encode(ReadOnlySpan<TCoordinate> coordinates, CancellationToken
 
             result = CreatePolyline(writer.WrittenMemory);
         } finally {
-            writer.ReturnBuffer();
+            if (rentedBuffer is not null) {
+                ArrayPool<char>.Shared.Return(rentedBuffer);
+            }
         }
 
         _logger
@@ -150,4 +162,3 @@ static void ValidateEmptyCoordinates(ref ReadOnlySpan<TCoordinate> coordinates,
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
     protected abstract void Write(TCoordinate item, IPolylineWriter writer);
 }
-

src/PolylineAlgorithm/Internal/PolylineWriter.cs

@@ -8,14 +8,13 @@ namespace PolylineAlgorithm.Internal;
 using PolylineAlgorithm.Abstraction;
 using PolylineAlgorithm.Internal.Diagnostics;
 using System;
-using System.Buffers;
 using System.Runtime.CompilerServices;
 
 /// <summary>
 /// Engine-owned stateful cursor that feeds values written by a formatter into the polyline encoding pipeline.
 /// </summary>
 /// <remarks>
-/// Each instance wraps an <see cref="ArrayPool{T}"/>-backed output buffer sized to the worst-case maximum
+/// Each instance wraps a caller-provided <see cref="char"/> buffer sized to the worst-case maximum
 /// capacity so that the buffer never needs to grow. The engine calls <see cref="BeginItem"/> before
 /// invoking the formatter for each item so that the slot index resets correctly while delta state is
 /// preserved across item boundaries.
@@ -27,8 +26,8 @@ internal sealed class PolylineWriter : IPolylineWriter {
     private int[] _previous;
     private int _slotIndex;
 
-    internal PolylineWriter(int capacity, uint precision) {
-        _buffer = ArrayPool<char>.Shared.Rent(capacity);
+    internal PolylineWriter(char[] buffer, uint precision) {
+        _buffer = buffer;
         _precision = precision;
         _previous = [];
         _slotIndex = 0;
@@ -68,12 +67,7 @@ public void Write(double value) {
 
     /// <summary>
     /// Returns the encoded polyline characters written so far.
-    /// The caller must not use this memory after <see cref="ReturnBuffer"/> is called.
+    /// The caller must not use this memory after the buffer is returned to <see cref="System.Buffers.ArrayPool{T}"/>.
     /// </summary>
     internal ReadOnlyMemory<char> WrittenMemory => _buffer.AsMemory(0, _position);
-
-    /// <summary>
-    /// Returns the rented buffer to the pool. Must be called exactly once when encoding is complete.
-    /// </summary>
-    internal void ReturnBuffer() => ArrayPool<char>.Shared.Return(_buffer);
 }