fix: Updates ArrayPool to STArrayPool for performance. (#968)

Projects/Server/Buffers/STArrayPool.cs

@@ -0,0 +1,324 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System;
+using System.Buffers;
+using System.Diagnostics;
+using System.Numerics;
+using System.Runtime.CompilerServices;
+
+namespace Server.Buffers;
+
+/**
+ * Adaptation of the ArrayPool<T>.Shared (TlsOverPerCoreLockedStacksArrayPool) for single threaded *unsafe* usage.
+ */
+public class STArrayPool<T> : ArrayPool<T>
+{
+    private const int StackArraySize = 8;
+    private const int BucketCount = 27; // SelectBucketIndex(1024 * 1024 * 1024 + 1)
+    private static readonly STArrayPool<T> _shared = new();
+
+    public static STArrayPool<T> Shared => _shared;
+
+    private static STArray[] _cacheBuckets;
+    private STArrayStack[] _buckets = new STArrayStack[BucketCount];
+
+    private STArrayPool() {}
+
+    public override T[] Rent(int minimumLength)
+    {
+        T[] buffer;
+
+        var bucketIndex = SelectBucketIndex(minimumLength);
+        var cachedBuckets = _cacheBuckets;
+        if (cachedBuckets is not null && (uint)bucketIndex < (uint)cachedBuckets.Length)
+        {
+            buffer = cachedBuckets[bucketIndex].Array;
+            if (buffer is not null)
+            {
+                cachedBuckets[bucketIndex].Array = null;
+                return buffer;
+            }
+        }
+
+        var buckets = _buckets;
+        if ((uint)bucketIndex < (uint)buckets.Length)
+        {
+            var b = buckets[bucketIndex];
+            if (b is not null)
+            {
+                buffer = b.TryPop();
+                if (buffer is not null)
+                {
+                    return buffer;
+                }
+            }
+
+            minimumLength = GetMaxSizeForBucket(bucketIndex);
+        }
+
+        if (minimumLength == 0)
+        {
+            // We aren't renting.
+            return Array.Empty<T>();
+        }
+
+        if (minimumLength < 0)
+        {
+            throw new ArgumentOutOfRangeException(nameof(minimumLength));
+        }
+
+        buffer = GC.AllocateUninitializedArray<T>(minimumLength);
+        return buffer;
+    }
+
+    public override void Return(T[] array, bool clearArray = false)
+    {
+        if (array is null)
+        {
+            throw new ArgumentNullException(nameof(array));
+        }
+
+        var bucketIndex = SelectBucketIndex(array.Length);
+        var cacheBuckets = _cacheBuckets ?? InitializeBuckets();
+
+        if ((uint)bucketIndex < (uint)_cacheBuckets!.Length)
+        {
+            if (clearArray)
+            {
+                Array.Clear(array);
+            }
+
+            if (array.Length != GetMaxSizeForBucket(bucketIndex))
+            {
+                throw new ArgumentException("Buffer is not from the pool", nameof(array));
+            }
+
+            ref var bucketArray = ref cacheBuckets[bucketIndex];
+            var prev = bucketArray.Array;
+            bucketArray = new STArray(array);
+            if (prev is not null)
+            {
+                var bucket = _buckets[bucketIndex] ?? CreateBucketStack(bucketIndex);
+                bucket.TryPush(prev);
+            }
+        }
+    }
+
+    public void ResetForTesting()
+    {
+        if (Core.IsRunningFromXUnit)
+        {
+            _cacheBuckets = null;
+            _buckets = new STArrayStack[BucketCount];
+        }
+    }
+
+    public bool Trim()
+    {
+        var ticks = Core.TickCount;
+        var pressure = GetMemoryPressure();
+
+        var buckets = _buckets;
+        for (var i = 0; i < buckets.Length; i++)
+        {
+            buckets[i]?.Trim(ticks, pressure, GetMaxSizeForBucket(i));
+        }
+
+        // Under high pressure, release all cached buckets
+        if (pressure == MemoryPressure.High)
+        {
+            Array.Clear(_cacheBuckets);
+        }
+        else
+        {
+            uint threshold = pressure switch
+            {
+                MemoryPressure.Medium => 10000,
+                _                     => 30000,
+            };
+
+            var cacheBuckets = _cacheBuckets;
+            for (var i = 0; i < cacheBuckets.Length; i++)
+            {
+                ref var b = ref cacheBuckets[i];
+
+                if (b.Array is null)
+                {
+                    continue;
+                }
+
+                var lastSeen = b.Ticks;
+                if (lastSeen == 0)
+                {
+                    b.Ticks = ticks;
+                }
+                else if (ticks - lastSeen >= threshold)
+                {
+                    b.Array = null;
+                }
+            }
+        }
+
+        return true;
+    }
+
+    private STArrayStack CreateBucketStack(int bucketIndex)
+    {
+        return _buckets[bucketIndex] = new STArrayStack();
+    }
+
+    private STArray[] InitializeBuckets()
+    {
+        Debug.Assert(_cacheBuckets is null, $"Non-null {nameof(_cacheBuckets)}");
+        var buckets = new STArray[BucketCount];
+        return _cacheBuckets = buckets;
+    }
+
+    // Buffers are bucketed so that a request between 2^(n-1) + 1 and 2^n is given a buffer of 2^n
+    // Bucket index is log2(bufferSize - 1) with the exception that buffers between 1 and 16 bytes
+    // are combined, and the index is slid down by 3 to compensate.
+    // Zero is a valid bufferSize, and it is assigned the highest bucket index so that zero-length
+    // buffers are not retained by the pool. The pool will return the Array.Empty singleton for these.
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    internal static int SelectBucketIndex(int bufferSize) => BitOperations.Log2((uint)bufferSize - 1 | 15) - 3;
+
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    internal static int GetMaxSizeForBucket(int binIndex)
+    {
+        int maxSize = 16 << binIndex;
+        Debug.Assert(maxSize >= 0);
+        return maxSize;
+    }
+
+    internal enum MemoryPressure
+    {
+        Low,
+        Medium,
+        High
+    }
+
+    internal static MemoryPressure GetMemoryPressure()
+    {
+        GCMemoryInfo memoryInfo = GC.GetGCMemoryInfo();
+
+        if (memoryInfo.MemoryLoadBytes >= memoryInfo.HighMemoryLoadThresholdBytes * 0.90)
+        {
+            return MemoryPressure.High;
+        }
+
+        if (memoryInfo.MemoryLoadBytes >= memoryInfo.HighMemoryLoadThresholdBytes * 0.70)
+        {
+            return MemoryPressure.Medium;
+        }
+
+        return MemoryPressure.Low;
+    }
+
+    private sealed class STArrayStack
+    {
+        // Maximum buffers we will store in our stack
+        private readonly T[][] _arrays = new T[StackArraySize * Environment.ProcessorCount][];
+        private int _count;
+        private long _ticks;
+
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public bool TryPush(T[] array)
+        {
+            var arrays = _arrays;
+            var count = _count;
+            if ((uint)count < (uint)_arrays.Length)
+            {
+                arrays[count] = array;
+                _count = count + 1;
+                return true;
+            }
+
+            return false;
+        }
+
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public T[] TryPop()
+        {
+            var arrays = _arrays;
+            var count = _count - 1;
+            if ((uint)count < (uint)arrays.Length)
+            {
+                var arr = arrays[count];
+                arrays[count] = null;
+                _count = count;
+                return arr;
+            }
+
+            return null;
+        }
+
+        public void Trim(long now, MemoryPressure pressure, int bucketSize)
+        {
+            if (_count == 0)
+            {
+                return;
+            }
+
+            // 10 seconds under high pressure, otherwise 60 seconds
+            var threshold = pressure == MemoryPressure.High ? 10000 : 60000;
+
+            if (_ticks == 0)
+            {
+                _ticks = now;
+                return;
+            }
+
+            if (now - _ticks <= threshold)
+            {
+                return;
+            }
+
+            int trimCount = 1;
+            switch (pressure)
+            {
+                case MemoryPressure.Medium:
+                    {
+                        trimCount = 2;
+                        break;
+                    }
+                case MemoryPressure.High:
+                    {
+                        if (bucketSize > 16384)
+                        {
+                            trimCount++;
+                        }
+
+                        var size = Unsafe.SizeOf<T>();
+                        if (size > 32)
+                        {
+                            trimCount += 2;
+                        }
+                        else if (size > 16)
+                        {
+                            trimCount++;
+                        }
+
+                        break;
+                    }
+            }
+
+            while (_count > 0 && trimCount-- > 0)
+            {
+                _arrays[--_count] = null;
+            }
+        }
+    }
+
+    private struct STArray
+    {
+        public T[] Array;
+        public long Ticks;
+
+        public STArray(T[] array)
+        {
+            Array = array;
+            Ticks = 0;
+        }
+    }
+}

Projects/Server/Buffers/SpanWriter.cs

@@ -1,6 +1,6 @@
 /*************************************************************************
  * ModernUO                                                              *
- * Copyright 2019-2020 - ModernUO Development Team                       *
+ * Copyright 2019-2022 - ModernUO Development Team                       *
  * Email: hi@modernuo.com                                                *
  * File: SpanWriter.cs                                                   *
  *                                                                       *
@@ -22,40 +22,41 @@ using System.Runtime.InteropServices;
 using System.Text;
 using Microsoft.Toolkit.HighPerformance;
 using Server;
+using Server.Buffers;
 using Server.Text;
 
-namespace System.Buffers
+namespace System.Buffers;
+
+public ref struct SpanWriter
 {
-    public ref struct SpanWriter
+    private readonly bool _resize;
+    private byte[] _arrayToReturnToPool;
+    private Span<byte> _buffer;
+    private int _position;
+
+    public int BytesWritten { get; private set; }
+
+    public int Position
     {
-        private readonly bool _resize;
-        private byte[] _arrayToReturnToPool;
-        private Span<byte> _buffer;
-        private int _position;
-
-        public int BytesWritten { get; private set; }
-
-        public int Position
+        get => _position;
+        private set
         {
-            get => _position;
-            private set
-            {
-                _position = value;
+            _position = value;
 
-                if (value > BytesWritten)
-                {
-                    BytesWritten = value;
-                }
+            if (value > BytesWritten)
+            {
+                BytesWritten = value;
             }
         }
+    }
 
-        public int Capacity => _buffer.Length;
+    public int Capacity => _buffer.Length;
 
-        public ReadOnlySpan<byte> Span => _buffer[..Position];
+    public ReadOnlySpan<byte> Span => _buffer[..Position];
 
-        public Span<byte> RawBuffer => _buffer;
+    public Span<byte> RawBuffer => _buffer;
 
-        /**
+    /**
          * Converts the writer to a Span<byte> using a SpanOwner.
          * If the buffer was stackalloc, it will be copied to a rented buffer.
          * Otherwise the existing rented buffer is used.
@@ -64,395 +65,394 @@ namespace System.Buffers
          * Do not use the SpanWriter after calling this method.
          * This method will effectively dispose of the SpanWriter and is therefore considered terminal.
          */
-        [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public SpanOwner ToSpan()
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public SpanOwner ToSpan()
+    {
+        var toReturn = _arrayToReturnToPool;
+
+        SpanOwner apo;
+        if (_position == 0)
         {
-            var toReturn = _arrayToReturnToPool;
-
-            SpanOwner apo;
-            if (_position == 0)
-            {
-                apo = new SpanOwner(_position, Array.Empty<byte>());
-                if (toReturn != null)
-                {
-                    ArrayPool<byte>.Shared.Return(toReturn);
-                }
-            }
-            else if (toReturn != null)
-            {
-                apo = new SpanOwner(_position, toReturn);
-            }
-            else
-            {
-                var buffer = ArrayPool<byte>.Shared.Rent(_position);
-                _buffer.CopyTo(buffer);
-                apo = new SpanOwner(_position, buffer);
-            }
-
-            this = default; // Don't allow two references to the same buffer
-            return apo;
-        }
-
-        [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public SpanWriter(Span<byte> initialBuffer, bool resize = false)
-        {
-            _resize = resize;
-            _buffer = initialBuffer;
-            _position = 0;
-            BytesWritten = 0;
-            _arrayToReturnToPool = null;
-        }
-
-        [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public SpanWriter(int initialCapacity, bool resize = false)
-        {
-            _resize = resize;
-            _arrayToReturnToPool = ArrayPool<byte>.Shared.Rent(initialCapacity);
-            _buffer = _arrayToReturnToPool;
-            _position = 0;
-            BytesWritten = 0;
-        }
-
-        [MethodImpl(MethodImplOptions.NoInlining)]
-        private void Grow(int additionalCapacity)
-        {
-            var newSize = Math.Max(BytesWritten + additionalCapacity, _buffer.Length * 2);
-            byte[] poolArray = ArrayPool<byte>.Shared.Rent(newSize);
-
-            _buffer[..BytesWritten].CopyTo(poolArray);
-
-            byte[] toReturn = _arrayToReturnToPool;
-            _buffer = _arrayToReturnToPool = poolArray;
+            apo = new SpanOwner(_position, Array.Empty<byte>());
             if (toReturn != null)
             {
-                ArrayPool<byte>.Shared.Return(toReturn);
+                STArrayPool<byte>.Shared.Return(toReturn);
             }
         }
-
-        [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        private void GrowIfNeeded(int count)
+        else if (toReturn != null)
         {
-            if (_position + count > _buffer.Length)
+            apo = new SpanOwner(_position, toReturn);
+        }
+        else
+        {
+            var buffer = STArrayPool<byte>.Shared.Rent(_position);
+            _buffer.CopyTo(buffer);
+            apo = new SpanOwner(_position, buffer);
+        }
+
+        this = default; // Don't allow two references to the same buffer
+        return apo;
+    }
+
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public SpanWriter(Span<byte> initialBuffer, bool resize = false)
+    {
+        _resize = resize;
+        _buffer = initialBuffer;
+        _position = 0;
+        BytesWritten = 0;
+        _arrayToReturnToPool = null;
+    }
+
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public SpanWriter(int initialCapacity, bool resize = false)
+    {
+        _resize = resize;
+        _arrayToReturnToPool = STArrayPool<byte>.Shared.Rent(initialCapacity);
+        _buffer = _arrayToReturnToPool;
+        _position = 0;
+        BytesWritten = 0;
+    }
+
+    [MethodImpl(MethodImplOptions.NoInlining)]
+    private void Grow(int additionalCapacity)
+    {
+        var newSize = Math.Max(BytesWritten + additionalCapacity, _buffer.Length * 2);
+        byte[] poolArray = STArrayPool<byte>.Shared.Rent(newSize);
+
+        _buffer[..BytesWritten].CopyTo(poolArray);
+
+        byte[] toReturn = _arrayToReturnToPool;
+        _buffer = _arrayToReturnToPool = poolArray;
+        if (toReturn != null)
+        {
+            STArrayPool<byte>.Shared.Return(toReturn);
+        }
+    }
+
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    private void GrowIfNeeded(int count)
+    {
+        if (_position + count > _buffer.Length)
+        {
+            if (!_resize)
             {
-                if (!_resize)
-                {
-                    throw new OutOfMemoryException();
-                }
-
-                Grow(count);
-            }
-        }
-
-        public ref byte GetPinnableReference() => ref MemoryMarshal.GetReference(_buffer);
-
-        public void EnsureCapacity(int capacity)
-        {
-            if (capacity > _buffer.Length)
-            {
-                if (!_resize)
-                {
-                    throw new OutOfMemoryException();
-                }
-
-                Grow(capacity - BytesWritten);
-            }
-        }
-
-        [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public unsafe void Write(bool value)
-        {
-            GrowIfNeeded(1);
-            _buffer[Position++] = *(byte*)&value;
-        }
-
-        [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public void Write(byte value)
-        {
-            GrowIfNeeded(1);
-            _buffer[Position++] = value;
-        }
-
-        [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public void Write(sbyte value)
-        {
-            GrowIfNeeded(1);
-            _buffer[Position++] = (byte)value;
-        }
-
-        [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public void Write(short value)
-        {
-            GrowIfNeeded(2);
-            BinaryPrimitives.WriteInt16BigEndian(_buffer[_position..], value);
-            Position += 2;
-        }
-
-        [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public void WriteLE(short value)
-        {
-            GrowIfNeeded(2);
-            BinaryPrimitives.WriteInt16LittleEndian(_buffer[_position..], value);
-            Position += 2;
-        }
-
-        [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public void Write(ushort value)
-        {
-            GrowIfNeeded(2);
-            BinaryPrimitives.WriteUInt16BigEndian(_buffer[_position..], value);
-            Position += 2;
-        }
-
-        [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public void WriteLE(ushort value)
-        {
-            GrowIfNeeded(2);
-            BinaryPrimitives.WriteUInt16LittleEndian(_buffer[_position..], value);
-            Position += 2;
-        }
-
-        [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public void Write(int value)
-        {
-            GrowIfNeeded(4);
-            BinaryPrimitives.WriteInt32BigEndian(_buffer[_position..], value);
-            Position += 4;
-        }
-
-        [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public void WriteLE(int value)
-        {
-            GrowIfNeeded(4);
-            BinaryPrimitives.WriteInt32LittleEndian(_buffer[_position..], value);
-            Position += 4;
-        }
-
-        [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public void Write(uint value)
-        {
-            GrowIfNeeded(4);
-            BinaryPrimitives.WriteUInt32BigEndian(_buffer[_position..], value);
-            Position += 4;
-        }
-
-        [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public void Write(Serial serial) => Write(serial.Value);
-
-        [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public void WriteLE(uint value)
-        {
-            GrowIfNeeded(4);
-            BinaryPrimitives.WriteUInt32LittleEndian(_buffer[_position..], value);
-            Position += 4;
-        }
-
-        [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public void Write(long value)
-        {
-            GrowIfNeeded(8);
-            BinaryPrimitives.WriteInt64BigEndian(_buffer[_position..], value);
-            Position += 8;
-        }
-
-        [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public void Write(ulong value)
-        {
-            GrowIfNeeded(8);
-            BinaryPrimitives.WriteUInt64BigEndian(_buffer[_position..], value);
-            Position += 8;
-        }
-
-        [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public void Write(ReadOnlySpan<byte> buffer)
-        {
-            var count = buffer.Length;
-            GrowIfNeeded(count);
-            buffer.CopyTo(_buffer[_position..]);
-            Position += count;
-        }
-
-        [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public void WriteAscii(char chr) => Write((byte)chr);
-
-        public void WriteString<T>(string value, Encoding encoding, int fixedLength = -1) where T : struct, IEquatable<T>
-        {
-            int sizeT = Unsafe.SizeOf<T>();
-
-            if (sizeT > 2)
-            {
-                throw new InvalidConstraintException("WriteString only accepts byte, sbyte, char, short, and ushort as a constraint");
+                throw new OutOfMemoryException();
             }
 
-            value ??= string.Empty;
+            Grow(count);
+        }
+    }
 
-            var charLength = Math.Min(fixedLength > -1 ? fixedLength : value.Length, value.Length);
-            var src = value.AsSpan(0, charLength);
+    public ref byte GetPinnableReference() => ref MemoryMarshal.GetReference(_buffer);
 
-            var byteCount = fixedLength > -1 ? fixedLength * sizeT : encoding.GetByteCount(value);
-            if (byteCount == 0)
+    public void EnsureCapacity(int capacity)
+    {
+        if (capacity > _buffer.Length)
+        {
+            if (!_resize)
             {
-                return;
+                throw new OutOfMemoryException();
             }
 
-            GrowIfNeeded(byteCount);
+            Grow(capacity - BytesWritten);
+        }
+    }
 
-            var bytesWritten = encoding.GetBytes(src, _buffer[_position..]);
-            Position += bytesWritten;
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public unsafe void Write(bool value)
+    {
+        GrowIfNeeded(1);
+        _buffer[Position++] = *(byte*)&value;
+    }
 
-            if (fixedLength > -1)
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public void Write(byte value)
+    {
+        GrowIfNeeded(1);
+        _buffer[Position++] = value;
+    }
+
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public void Write(sbyte value)
+    {
+        GrowIfNeeded(1);
+        _buffer[Position++] = (byte)value;
+    }
+
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public void Write(short value)
+    {
+        GrowIfNeeded(2);
+        BinaryPrimitives.WriteInt16BigEndian(_buffer[_position..], value);
+        Position += 2;
+    }
+
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public void WriteLE(short value)
+    {
+        GrowIfNeeded(2);
+        BinaryPrimitives.WriteInt16LittleEndian(_buffer[_position..], value);
+        Position += 2;
+    }
+
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public void Write(ushort value)
+    {
+        GrowIfNeeded(2);
+        BinaryPrimitives.WriteUInt16BigEndian(_buffer[_position..], value);
+        Position += 2;
+    }
+
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public void WriteLE(ushort value)
+    {
+        GrowIfNeeded(2);
+        BinaryPrimitives.WriteUInt16LittleEndian(_buffer[_position..], value);
+        Position += 2;
+    }
+
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public void Write(int value)
+    {
+        GrowIfNeeded(4);
+        BinaryPrimitives.WriteInt32BigEndian(_buffer[_position..], value);
+        Position += 4;
+    }
+
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public void WriteLE(int value)
+    {
+        GrowIfNeeded(4);
+        BinaryPrimitives.WriteInt32LittleEndian(_buffer[_position..], value);
+        Position += 4;
+    }
+
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public void Write(uint value)
+    {
+        GrowIfNeeded(4);
+        BinaryPrimitives.WriteUInt32BigEndian(_buffer[_position..], value);
+        Position += 4;
+    }
+
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public void Write(Serial serial) => Write(serial.Value);
+
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public void WriteLE(uint value)
+    {
+        GrowIfNeeded(4);
+        BinaryPrimitives.WriteUInt32LittleEndian(_buffer[_position..], value);
+        Position += 4;
+    }
+
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public void Write(long value)
+    {
+        GrowIfNeeded(8);
+        BinaryPrimitives.WriteInt64BigEndian(_buffer[_position..], value);
+        Position += 8;
+    }
+
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public void Write(ulong value)
+    {
+        GrowIfNeeded(8);
+        BinaryPrimitives.WriteUInt64BigEndian(_buffer[_position..], value);
+        Position += 8;
+    }
+
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public void Write(ReadOnlySpan<byte> buffer)
+    {
+        var count = buffer.Length;
+        GrowIfNeeded(count);
+        buffer.CopyTo(_buffer[_position..]);
+        Position += count;
+    }
+
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public void WriteAscii(char chr) => Write((byte)chr);
+
+    public void WriteString<T>(string value, Encoding encoding, int fixedLength = -1) where T : struct, IEquatable<T>
+    {
+        int sizeT = Unsafe.SizeOf<T>();
+
+        if (sizeT > 2)
+        {
+            throw new InvalidConstraintException("WriteString only accepts byte, sbyte, char, short, and ushort as a constraint");
+        }
+
+        value ??= string.Empty;
+
+        var charLength = Math.Min(fixedLength > -1 ? fixedLength : value.Length, value.Length);
+        var src = value.AsSpan(0, charLength);
+
+        var byteCount = fixedLength > -1 ? fixedLength * sizeT : encoding.GetByteCount(value);
+        if (byteCount == 0)
+        {
+            return;
+        }
+
+        GrowIfNeeded(byteCount);
+
+        var bytesWritten = encoding.GetBytes(src, _buffer[_position..]);
+        Position += bytesWritten;
+
+        if (fixedLength > -1)
+        {
+            var extra = fixedLength * sizeT - bytesWritten;
+            if (extra > 0)
             {
-                var extra = fixedLength * sizeT - bytesWritten;
-                if (extra > 0)
-                {
-                    Clear(extra);
-                }
+                Clear(extra);
             }
         }
+    }
 
-        [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public void WriteLittleUni(string value) => WriteString<char>(value, TextEncoding.UnicodeLE);
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public void WriteLittleUni(string value) => WriteString<char>(value, TextEncoding.UnicodeLE);
 
-        [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public void WriteLittleUniNull(string value)
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public void WriteLittleUniNull(string value)
+    {
+        WriteString<char>(value, TextEncoding.UnicodeLE);
+        Write((ushort)0);
+    }
+
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public void WriteLittleUni(string value, int fixedLength) => WriteString<char>(value, TextEncoding.UnicodeLE, fixedLength);
+
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public void WriteBigUni(string value) => WriteString<char>(value, TextEncoding.Unicode);
+
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public void WriteBigUniNull(string value)
+    {
+        WriteString<char>(value, TextEncoding.Unicode);
+        Write((ushort)0); // '\0'
+    }
+
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public void WriteBigUni(string value, int fixedLength) => WriteString<char>(value, TextEncoding.Unicode, fixedLength);
+
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public void WriteUTF8(string value) => WriteString<byte>(value, TextEncoding.UTF8);
+
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public void WriteUTF8Null(string value)
+    {
+        WriteString<byte>(value, TextEncoding.UTF8);
+        Write((byte)0); // '\0'
+    }
+
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public void WriteAscii(string value) => WriteString<byte>(value, Encoding.ASCII);
+
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public void WriteAsciiNull(string value)
+    {
+        WriteString<byte>(value, Encoding.ASCII);
+        Write((byte)0); // '\0'
+    }
+
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public void WriteAscii(string value, int fixedLength) => WriteString<byte>(value, Encoding.ASCII, fixedLength);
+
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public void Clear(int count)
+    {
+        GrowIfNeeded(count);
+        _buffer.Slice(_position, count).Clear();
+        Position += count;
+    }
+
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public int Seek(int offset, SeekOrigin origin)
+    {
+        Debug.Assert(
+            origin != SeekOrigin.End || _resize || offset <= 0,
+            "Attempting to seek to a position beyond capacity using SeekOrigin.End without resize"
+        );
+
+        Debug.Assert(
+            origin != SeekOrigin.End || offset >= -_buffer.Length,
+
+            "Attempting to seek to a negative position using SeekOrigin.End"
+        );
+
+        Debug.Assert(
+            origin != SeekOrigin.Begin || offset >= 0,
+            "Attempting to seek to a negative position using SeekOrigin.Begin"
+        );
+
+        Debug.Assert(
+            origin != SeekOrigin.Begin || _resize || offset <= _buffer.Length,
+            "Attempting to seek to a position beyond the capacity using SeekOrigin.Begin without resize"
+        );
+
+        Debug.Assert(
+            origin != SeekOrigin.Current || _position + offset >= 0,
+            "Attempting to seek to a negative position using SeekOrigin.Current"
+        );
+
+        Debug.Assert(
+            origin != SeekOrigin.Current || _resize || _position + offset <= _buffer.Length,
+            "Attempting to seek to a position beyond the capacity using SeekOrigin.Current without resize"
+        );
+
+        var newPosition = Math.Max(0, origin switch
         {
-            WriteString<char>(value, TextEncoding.UnicodeLE);
-            Write((ushort)0);
+            SeekOrigin.Current => _position + offset,
+            SeekOrigin.End     => BytesWritten + offset,
+            _                  => offset // Begin
+        });
+
+        if (newPosition >= _buffer.Length)
+        {
+            Grow(newPosition - _buffer.Length + 1);
         }
 
-        [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public void WriteLittleUni(string value, int fixedLength) => WriteString<char>(value, TextEncoding.UnicodeLE, fixedLength);
+        return Position = newPosition;
+    }
 
-        [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public void WriteBigUni(string value) => WriteString<char>(value, TextEncoding.Unicode);
-
-        [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public void WriteBigUniNull(string value)
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public void Dispose()
+    {
+        byte[] toReturn = _arrayToReturnToPool;
+        this = default; // for safety, to avoid using pooled array if this instance is erroneously appended to again
+        if (toReturn != null)
         {
-            WriteString<char>(value, TextEncoding.Unicode);
-            Write((ushort)0); // '\0'
+            STArrayPool<byte>.Shared.Return(toReturn);
+        }
+    }
+
+    public struct SpanOwner : IDisposable
+    {
+        private readonly int _length;
+        private readonly byte[] _arrayToReturnToPool;
+
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        internal SpanOwner(int length, byte[] buffer)
+        {
+            _length = length;
+            _arrayToReturnToPool = buffer;
         }
 
-        [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public void WriteBigUni(string value, int fixedLength) => WriteString<char>(value, TextEncoding.Unicode, fixedLength);
-
-        [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public void WriteUTF8(string value) => WriteString<byte>(value, TextEncoding.UTF8);
-
-        [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public void WriteUTF8Null(string value)
+        public Span<byte> Span
         {
-            WriteString<byte>(value, TextEncoding.UTF8);
-            Write((byte)0); // '\0'
-        }
-
-        [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public void WriteAscii(string value) => WriteString<byte>(value, Encoding.ASCII);
-
-        [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public void WriteAsciiNull(string value)
-        {
-            WriteString<byte>(value, Encoding.ASCII);
-            Write((byte)0); // '\0'
-        }
-
-        [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public void WriteAscii(string value, int fixedLength) => WriteString<byte>(value, Encoding.ASCII, fixedLength);
-
-        [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public void Clear(int count)
-        {
-            GrowIfNeeded(count);
-            _buffer.Slice(_position, count).Clear();
-            Position += count;
-        }
-
-        [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public int Seek(int offset, SeekOrigin origin)
-        {
-            Debug.Assert(
-                origin != SeekOrigin.End || _resize || offset <= 0,
-                "Attempting to seek to a position beyond capacity using SeekOrigin.End without resize"
-            );
-
-            Debug.Assert(
-                origin != SeekOrigin.End || offset >= -_buffer.Length,
-
-                "Attempting to seek to a negative position using SeekOrigin.End"
-            );
-
-            Debug.Assert(
-                origin != SeekOrigin.Begin || offset >= 0,
-                "Attempting to seek to a negative position using SeekOrigin.Begin"
-            );
-
-            Debug.Assert(
-                origin != SeekOrigin.Begin || _resize || offset <= _buffer.Length,
-                "Attempting to seek to a position beyond the capacity using SeekOrigin.Begin without resize"
-            );
-
-            Debug.Assert(
-                origin != SeekOrigin.Current || _position + offset >= 0,
-                "Attempting to seek to a negative position using SeekOrigin.Current"
-            );
-
-            Debug.Assert(
-                origin != SeekOrigin.Current || _resize || _position + offset <= _buffer.Length,
-                "Attempting to seek to a position beyond the capacity using SeekOrigin.Current without resize"
-            );
-
-            var newPosition = Math.Max(0, origin switch
-            {
-                SeekOrigin.Current => _position + offset,
-                SeekOrigin.End     => BytesWritten + offset,
-                _                  => offset // Begin
-            });
-
-            if (newPosition >= _buffer.Length)
-            {
-                Grow(newPosition - _buffer.Length + 1);
-            }
-
-            return Position = newPosition;
+            [MethodImpl(MethodImplOptions.AggressiveInlining)]
+            get => MemoryMarshal.CreateSpan(ref _arrayToReturnToPool.DangerousGetReference(), _length);
         }
 
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
         public void Dispose()
         {
             byte[] toReturn = _arrayToReturnToPool;
-            this = default; // for safety, to avoid using pooled array if this instance is erroneously appended to again
-            if (toReturn != null)
+            this = default;
+            if (_length > 0)
             {
-                ArrayPool<byte>.Shared.Return(toReturn);
-            }
-        }
-
-        public struct SpanOwner : IDisposable
-        {
-            private readonly int _length;
-            private readonly byte[] _arrayToReturnToPool;
-
-            [MethodImpl(MethodImplOptions.AggressiveInlining)]
-            internal SpanOwner(int length, byte[] buffer)
-            {
-                _length = length;
-                _arrayToReturnToPool = buffer;
-            }
-
-            public Span<byte> Span
-            {
-                [MethodImpl(MethodImplOptions.AggressiveInlining)]
-                get => MemoryMarshal.CreateSpan(ref _arrayToReturnToPool.DangerousGetReference(), _length);
-            }
-
-            [MethodImpl(MethodImplOptions.AggressiveInlining)]
-            public void Dispose()
-            {
-                byte[] toReturn = _arrayToReturnToPool;
-                this = default;
-                if (_length > 0)
-                {
-                    ArrayPool<byte>.Shared.Return(toReturn);
-                }
+                STArrayPool<byte>.Shared.Return(toReturn);
             }
         }
     }

Projects/Server/Buffers/ValueStringBuilder.cs

@@ -2,473 +2,471 @@
 // The .NET Foundation licenses this file to you under the MIT license.
 
 using System;
-using System.Buffers;
 using System.Globalization;
 using System.Runtime.CompilerServices;
 using System.Runtime.InteropServices;
 
-namespace Server.Buffers
+namespace Server.Buffers;
+
+public ref struct ValueStringBuilder
 {
-    public ref struct ValueStringBuilder
+    private char[] _arrayToReturnToPool;
+    private Span<char> _chars;
+    private int _length;
+
+    // If this ctor is used, you cannot pass in stackalloc ROS for append/replace.
+    public ValueStringBuilder(ReadOnlySpan<char> initialString) : this(initialString.Length)
     {
-        private char[] _arrayToReturnToPool;
-        private Span<char> _chars;
-        private int _length;
+        Append(initialString);
+    }
 
-        // If this ctor is used, you cannot pass in stackalloc ROS for append/replace.
-        public ValueStringBuilder(ReadOnlySpan<char> initialString) : this(initialString.Length)
+    public ValueStringBuilder(ReadOnlySpan<char> initialString, Span<char> initialBuffer) : this(initialBuffer)
+    {
+        Append(initialString);
+    }
+
+    public ValueStringBuilder(Span<char> initialBuffer)
+    {
+        _arrayToReturnToPool = null;
+        _chars = initialBuffer;
+        _length = 0;
+    }
+
+    // If this ctor is used, you cannot pass in stackalloc ROS for append/replace.
+    public ValueStringBuilder(int initialCapacity)
+    {
+        _arrayToReturnToPool = STArrayPool<char>.Shared.Rent(initialCapacity);
+        _chars = _arrayToReturnToPool;
+        _length = 0;
+    }
+
+    public int Length => _length;
+
+    public int Capacity => _chars.Length;
+
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public void Reset()
+    {
+        _length = 0;
+    }
+
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public void EnsureCapacity(int capacity)
+    {
+        if (capacity > _chars.Length)
         {
-            Append(initialString);
-        }
-
-        public ValueStringBuilder(ReadOnlySpan<char> initialString, Span<char> initialBuffer) : this(initialBuffer)
-        {
-            Append(initialString);
-        }
-
-        public ValueStringBuilder(Span<char> initialBuffer)
-        {
-            _arrayToReturnToPool = null;
-            _chars = initialBuffer;
-            _length = 0;
-        }
-
-        // If this ctor is used, you cannot pass in stackalloc ROS for append/replace.
-        public ValueStringBuilder(int initialCapacity)
-        {
-            _arrayToReturnToPool = ArrayPool<char>.Shared.Rent(initialCapacity);
-            _chars = _arrayToReturnToPool;
-            _length = 0;
-        }
-
-        public int Length => _length;
-
-        public int Capacity => _chars.Length;
-
-        [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public void Reset()
-        {
-            _length = 0;
-        }
-
-        [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public void EnsureCapacity(int capacity)
-        {
-            if (capacity > _chars.Length)
-            {
-                Grow(capacity - Length);
-            }
-        }
-
-        /// <summary>
-        /// Get a pinnable reference to the builder.
-        /// Does not ensure there is a null char after <see cref="Length"/>
-        /// This overload is pattern matched in the C# 7.3+ compiler so you can omit
-        /// the explicit method call, and write eg "fixed (char* c = builder)"
-        /// </summary>
-        public ref char GetPinnableReference() => ref MemoryMarshal.GetReference(_chars);
-
-        /// <summary>
-        /// Get a pinnable reference to the builder.
-        /// </summary>
-        /// <param name="terminate">Ensures that the builder has a null char after <see cref="Length"/></param>
-        public ref char GetPinnableReference(bool terminate)
-        {
-            if (terminate)
-            {
-                EnsureCapacity(_length + 1);
-                _chars[_length] = '\0';
-            }
-            return ref MemoryMarshal.GetReference(_chars);
-        }
-
-        public ref char this[int index] => ref _chars[index];
-
-        [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public override string ToString() => _chars[.._length].ToString();
-
-        /// <summary>Returns the underlying storage of the builder.</summary>
-        public Span<char> RawChars => _chars;
-
-        /// <summary>
-        /// Returns a span around the contents of the builder.
-        /// </summary>
-        /// <param name="terminate">Ensures that the builder has a null char after <see cref="Length"/></param>
-        public ReadOnlySpan<char> AsSpan(bool terminate)
-        {
-            if (terminate)
-            {
-                EnsureCapacity(_length + 1);
-                _chars[_length] = '\0';
-            }
-            return _chars[.._length];
-        }
-
-        [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public ReadOnlySpan<char> AsSpan() => _chars[.._length];
-
-        [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public ReadOnlySpan<char> AsSpan(int start) => _chars[start..];
-
-        [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public ReadOnlySpan<char> AsSpan(int start, int length) => _chars.Slice(start, length);
-
-        [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public bool TryCopyTo(Span<char> destination, out int charsWritten)
-        {
-            if (_chars[.._length].TryCopyTo(destination))
-            {
-                charsWritten = _length;
-                return true;
-            }
-
-            charsWritten = 0;
-            return false;
-        }
-
-        [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public void Insert(int index, char value, int count)
-        {
-            if (_length > _chars.Length - count)
-            {
-                Grow(count);
-            }
-
-            int remaining = _length - index;
-            _chars.Slice(index, remaining).CopyTo(_chars[(index + count)..]);
-            _chars.Slice(index, count).Fill(value);
-            _length += count;
-        }
-
-        [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public void Insert(int index, string s)
-        {
-            if (s == null)
-            {
-                return;
-            }
-
-            int count = s.Length;
-
-            if (_length > _chars.Length - count)
-            {
-                Grow(count);
-            }
-
-            int remaining = _length - index;
-            _chars.Slice(index, remaining).CopyTo(_chars[(index + count)..]);
-            s.AsSpan().CopyTo(_chars[index..]);
-            _length += count;
-        }
-
-        [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public void Append(char c)
-        {
-            int pos = _length;
-            if ((uint)pos < (uint)_chars.Length)
-            {
-                _chars[pos] = c;
-                _length = pos + 1;
-            }
-            else
-            {
-                GrowAndAppend(c);
-            }
-        }
-
-        [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public void Append(int value, NumberFormatInfo info = null)
-        {
-            if (value >= 0)
-            {
-                Append((uint)value);
-                return;
-            }
-
-            Append((info ?? NumberFormatInfo.CurrentInfo).NegativeSign);
-            Append((uint)-value);
-        }
-
-        [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public unsafe void Append(uint value)
-        {
-            int bufferLength = value.CountDigits();
-
-            int pos = _length;
-            if ((uint)pos + (uint)bufferLength >= _chars.Length)
-            {
-                Grow(bufferLength);
-            }
-
-            if (bufferLength == 1)
-            {
-                _chars[pos] = (char)(value + '0');
-                _length = pos + 1;
-                return;
-            }
-
-            fixed (char* buffer = _chars[pos..])
-            {
-                char* p = buffer + bufferLength;
-                do
-                {
-                    value = Utility.DivRem(value, 10, out uint remainder);
-                    *--p = (char)(remainder + '0');
-                } while (value != 0);
-            }
-
-            _length = pos + bufferLength;
-        }
-
-        [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public void Append(string s)
-        {
-            if (s == null)
-            {
-                return;
-            }
-
-            int pos = _length;
-            if (s.Length == 1 && (uint)pos < (uint)_chars.Length) // very common case, e.g. appending strings from NumberFormatInfo like separators, percent symbols, etc.
-            {
-                _chars[pos] = s[0];
-                _length = pos + 1;
-            }
-            else
-            {
-                AppendSlow(s);
-            }
-        }
-
-        [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public void AppendLine(string s)
-        {
-            if (s == null)
-            {
-                return;
-            }
-
-            // very common case, e.g. appending strings from NumberFormatInfo like separators, percent symbols, etc.
-            if (s.Length == 1)
-            {
-                Append(s[0]);
-            }
-            else
-            {
-                AppendSlow(s);
-            }
-
-            Append(Environment.NewLine);
-        }
-
-        [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        private void AppendSlow(string s)
-        {
-            int pos = _length;
-            if (pos > _chars.Length - s.Length)
-            {
-                Grow(s.Length);
-            }
-
-            s.AsSpan().CopyTo(_chars[pos..]);
-            _length += s.Length;
-        }
-
-        [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public void Append(char c, int count)
-        {
-            if (_length > _chars.Length - count)
-            {
-                Grow(count);
-            }
-
-            Span<char> dst = _chars.Slice(_length, count);
-            for (int i = 0; i < dst.Length; i++)
-            {
-                dst[i] = c;
-            }
-            _length += count;
-        }
-
-        [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public unsafe void Append(char* value, int length)
-        {
-            int pos = _length;
-            if (pos > _chars.Length - length)
-            {
-                Grow(length);
-            }
-
-            Span<char> dst = _chars.Slice(_length, length);
-            for (int i = 0; i < dst.Length; i++)
-            {
-                dst[i] = *value++;
-            }
-            _length += length;
-        }
-
-        [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public void Append(ReadOnlySpan<char> value)
-        {
-            int pos = _length;
-            if (pos > _chars.Length - value.Length)
-            {
-                Grow(value.Length);
-            }
-
-            value.CopyTo(_chars[_length..]);
-            _length += value.Length;
-        }
-
-        [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public Span<char> AppendSpan(int length)
-        {
-            int origPos = _length;
-            if (origPos > _chars.Length - length)
-            {
-                Grow(length);
-            }
-
-            _length = origPos + length;
-            return _chars.Slice(origPos, length);
-        }
-
-        [MethodImpl(MethodImplOptions.NoInlining)]
-        private void GrowAndAppend(char c)
-        {
-            Grow(1);
-            Append(c);
-        }
-
-#nullable enable
-        /// <summary>
-        /// Resize the internal buffer either by doubling current buffer size or
-        /// by adding <paramref name="additionalCapacityBeyondPos"/> to
-        /// <see cref="Length"/> whichever is greater.
-        /// </summary>
-        /// <param name="additionalCapacityBeyondPos">
-        /// Number of chars requested beyond current position.
-        /// </param>
-        [MethodImpl(MethodImplOptions.NoInlining)]
-        private void Grow(int additionalCapacityBeyondPos)
-        {
-            char[] poolArray = ArrayPool<char>.Shared.Rent(Math.Max(_length + additionalCapacityBeyondPos, _chars.Length * 2));
-
-            _chars[.._length].CopyTo(poolArray);
-
-            char[] toReturn = _arrayToReturnToPool;
-            _chars = _arrayToReturnToPool = poolArray;
-            if (toReturn != null)
-            {
-                ArrayPool<char>.Shared.Return(toReturn);
-            }
-        }
-
-        [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public void Dispose()
-        {
-            char[] toReturn = _arrayToReturnToPool;
-            this = default; // for safety, to avoid using pooled array if this instance is erroneously appended to again
-            if (toReturn != null)
-            {
-                ArrayPool<char>.Shared.Return(toReturn);
-            }
-        }
-#nullable restore
-
-        [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public void ReplaceAny(ReadOnlySpan<char> oldChars, ReadOnlySpan<char> newChars, int startIndex, int count)
-        {
-            int currentLength = _length;
-            if ((uint)startIndex > (uint)currentLength)
-            {
-                throw new ArgumentOutOfRangeException(nameof(startIndex));
-            }
-
-            if (count < 0 || startIndex > currentLength - count)
-            {
-                throw new ArgumentOutOfRangeException(nameof(count));
-            }
-
-            var slice = _chars;
-
-            while (true)
-            {
-                var indexOf = slice.IndexOfAny(oldChars);
-                if (indexOf == -1)
-                {
-                    break;
-                }
-
-                var chr = slice[indexOf];
-
-                slice[indexOf] = newChars[oldChars.IndexOf(chr)];
-                slice = slice[(indexOf + 1)..];
-            }
-        }
-
-        [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public void Replace(char oldChar, char newChar, int startIndex, int count)
-        {
-            int currentLength = _length;
-            if ((uint)startIndex > (uint)currentLength)
-            {
-                throw new ArgumentOutOfRangeException(nameof(startIndex));
-            }
-
-            if (count < 0 || startIndex > currentLength - count)
-            {
-                throw new ArgumentOutOfRangeException(nameof(count));
-            }
-
-            var slice = _chars;
-
-            while (true)
-            {
-                var indexOf = slice.IndexOf(oldChar);
-                if (indexOf == -1)
-                {
-                    break;
-                }
-
-                slice[indexOf] = newChar;
-                slice = slice[(indexOf + 1)..];
-            }
-        }
-
-        [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public void Remove(int startIndex, int length)
-        {
-            if (length < 0)
-            {
-                throw new ArgumentOutOfRangeException(nameof(length));
-            }
-
-            if (startIndex < 0)
-            {
-                throw new ArgumentOutOfRangeException(nameof(startIndex));
-            }
-
-            if (length > _length - startIndex)
-            {
-                throw new ArgumentOutOfRangeException(nameof(length));
-            }
-
-            if (startIndex == 0)
-            {
-                _chars = _chars[length..];
-            }
-            else if (startIndex + length == _length)
-            {
-                _chars = _chars[..startIndex];
-            }
-            else
-            {
-                // Somewhere in the middle, this will be slow
-                _chars[(startIndex + length)..].CopyTo(_chars[startIndex..]);
-            }
-
-            _length -= length;
+            Grow(capacity - Length);
         }
     }
+
+    /// <summary>
+    /// Get a pinnable reference to the builder.
+    /// Does not ensure there is a null char after <see cref="Length"/>
+    /// This overload is pattern matched in the C# 7.3+ compiler so you can omit
+    /// the explicit method call, and write eg "fixed (char* c = builder)"
+    /// </summary>
+    public ref char GetPinnableReference() => ref MemoryMarshal.GetReference(_chars);
+
+    /// <summary>
+    /// Get a pinnable reference to the builder.
+    /// </summary>
+    /// <param name="terminate">Ensures that the builder has a null char after <see cref="Length"/></param>
+    public ref char GetPinnableReference(bool terminate)
+    {
+        if (terminate)
+        {
+            EnsureCapacity(_length + 1);
+            _chars[_length] = '\0';
+        }
+        return ref MemoryMarshal.GetReference(_chars);
+    }
+
+    public ref char this[int index] => ref _chars[index];
+
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public override string ToString() => _chars[.._length].ToString();
+
+    /// <summary>Returns the underlying storage of the builder.</summary>
+    public Span<char> RawChars => _chars;
+
+    /// <summary>
+    /// Returns a span around the contents of the builder.
+    /// </summary>
+    /// <param name="terminate">Ensures that the builder has a null char after <see cref="Length"/></param>
+    public ReadOnlySpan<char> AsSpan(bool terminate)
+    {
+        if (terminate)
+        {
+            EnsureCapacity(_length + 1);
+            _chars[_length] = '\0';
+        }
+        return _chars[.._length];
+    }
+
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public ReadOnlySpan<char> AsSpan() => _chars[.._length];
+
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public ReadOnlySpan<char> AsSpan(int start) => _chars[start..];
+
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public ReadOnlySpan<char> AsSpan(int start, int length) => _chars.Slice(start, length);
+
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public bool TryCopyTo(Span<char> destination, out int charsWritten)
+    {
+        if (_chars[.._length].TryCopyTo(destination))
+        {
+            charsWritten = _length;
+            return true;
+        }
+
+        charsWritten = 0;
+        return false;
+    }
+
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public void Insert(int index, char value, int count)
+    {
+        if (_length > _chars.Length - count)
+        {
+            Grow(count);
+        }
+
+        int remaining = _length - index;
+        _chars.Slice(index, remaining).CopyTo(_chars[(index + count)..]);
+        _chars.Slice(index, count).Fill(value);
+        _length += count;
+    }
+
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public void Insert(int index, string s)
+    {
+        if (s == null)
+        {
+            return;
+        }
+
+        int count = s.Length;
+
+        if (_length > _chars.Length - count)
+        {
+            Grow(count);
+        }
+
+        int remaining = _length - index;
+        _chars.Slice(index, remaining).CopyTo(_chars[(index + count)..]);
+        s.AsSpan().CopyTo(_chars[index..]);
+        _length += count;
+    }
+
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public void Append(char c)
+    {
+        int pos = _length;
+        if ((uint)pos < (uint)_chars.Length)
+        {
+            _chars[pos] = c;
+            _length = pos + 1;
+        }
+        else
+        {
+            GrowAndAppend(c);
+        }
+    }
+
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public void Append(int value, NumberFormatInfo info = null)
+    {
+        if (value >= 0)
+        {
+            Append((uint)value);
+            return;
+        }
+
+        Append((info ?? NumberFormatInfo.CurrentInfo).NegativeSign);
+        Append((uint)-value);
+    }
+
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public unsafe void Append(uint value)
+    {
+        int bufferLength = value.CountDigits();
+
+        int pos = _length;
+        if ((uint)pos + (uint)bufferLength >= _chars.Length)
+        {
+            Grow(bufferLength);
+        }
+
+        if (bufferLength == 1)
+        {
+            _chars[pos] = (char)(value + '0');
+            _length = pos + 1;
+            return;
+        }
+
+        fixed (char* buffer = _chars[pos..])
+        {
+            char* p = buffer + bufferLength;
+            do
+            {
+                value = Utility.DivRem(value, 10, out uint remainder);
+                *--p = (char)(remainder + '0');
+            } while (value != 0);
+        }
+
+        _length = pos + bufferLength;
+    }
+
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public void Append(string s)
+    {
+        if (s == null)
+        {
+            return;
+        }
+
+        int pos = _length;
+        if (s.Length == 1 && (uint)pos < (uint)_chars.Length) // very common case, e.g. appending strings from NumberFormatInfo like separators, percent symbols, etc.
+        {
+            _chars[pos] = s[0];
+            _length = pos + 1;
+        }
+        else
+        {
+            AppendSlow(s);
+        }
+    }
+
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public void AppendLine(string s)
+    {
+        if (s == null)
+        {
+            return;
+        }
+
+        // very common case, e.g. appending strings from NumberFormatInfo like separators, percent symbols, etc.
+        if (s.Length == 1)
+        {
+            Append(s[0]);
+        }
+        else
+        {
+            AppendSlow(s);
+        }
+
+        Append(Environment.NewLine);
+    }
+
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    private void AppendSlow(string s)
+    {
+        int pos = _length;
+        if (pos > _chars.Length - s.Length)
+        {
+            Grow(s.Length);
+        }
+
+        s.AsSpan().CopyTo(_chars[pos..]);
+        _length += s.Length;
+    }
+
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public void Append(char c, int count)
+    {
+        if (_length > _chars.Length - count)
+        {
+            Grow(count);
+        }
+
+        Span<char> dst = _chars.Slice(_length, count);
+        for (int i = 0; i < dst.Length; i++)
+        {
+            dst[i] = c;
+        }
+        _length += count;
+    }
+
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public unsafe void Append(char* value, int length)
+    {
+        int pos = _length;
+        if (pos > _chars.Length - length)
+        {
+            Grow(length);
+        }
+
+        Span<char> dst = _chars.Slice(_length, length);
+        for (int i = 0; i < dst.Length; i++)
+        {
+            dst[i] = *value++;
+        }
+        _length += length;
+    }
+
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public void Append(ReadOnlySpan<char> value)
+    {
+        int pos = _length;
+        if (pos > _chars.Length - value.Length)
+        {
+            Grow(value.Length);
+        }
+
+        value.CopyTo(_chars[_length..]);
+        _length += value.Length;
+    }
+
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public Span<char> AppendSpan(int length)
+    {
+        int origPos = _length;
+        if (origPos > _chars.Length - length)
+        {
+            Grow(length);
+        }
+
+        _length = origPos + length;
+        return _chars.Slice(origPos, length);
+    }
+
+    [MethodImpl(MethodImplOptions.NoInlining)]
+    private void GrowAndAppend(char c)
+    {
+        Grow(1);
+        Append(c);
+    }
+
+#nullable enable
+    /// <summary>
+    /// Resize the internal buffer either by doubling current buffer size or
+    /// by adding <paramref name="additionalCapacityBeyondPos"/> to
+    /// <see cref="Length"/> whichever is greater.
+    /// </summary>
+    /// <param name="additionalCapacityBeyondPos">
+    /// Number of chars requested beyond current position.
+    /// </param>
+    [MethodImpl(MethodImplOptions.NoInlining)]
+    private void Grow(int additionalCapacityBeyondPos)
+    {
+        char[] poolArray = STArrayPool<char>.Shared.Rent(Math.Max(_length + additionalCapacityBeyondPos, _chars.Length * 2));
+
+        _chars[.._length].CopyTo(poolArray);
+
+        char[] toReturn = _arrayToReturnToPool;
+        _chars = _arrayToReturnToPool = poolArray;
+        if (toReturn != null)
+        {
+            STArrayPool<char>.Shared.Return(toReturn);
+        }
+    }
+
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public void Dispose()
+    {
+        char[] toReturn = _arrayToReturnToPool;
+        this = default; // for safety, to avoid using pooled array if this instance is erroneously appended to again
+        if (toReturn != null)
+        {
+            STArrayPool<char>.Shared.Return(toReturn);
+        }
+    }
+#nullable restore
+
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public void ReplaceAny(ReadOnlySpan<char> oldChars, ReadOnlySpan<char> newChars, int startIndex, int count)
+    {
+        int currentLength = _length;
+        if ((uint)startIndex > (uint)currentLength)
+        {
+            throw new ArgumentOutOfRangeException(nameof(startIndex));
+        }
+
+        if (count < 0 || startIndex > currentLength - count)
+        {
+            throw new ArgumentOutOfRangeException(nameof(count));
+        }
+
+        var slice = _chars;
+
+        while (true)
+        {
+            var indexOf = slice.IndexOfAny(oldChars);
+            if (indexOf == -1)
+            {
+                break;
+            }
+
+            var chr = slice[indexOf];
+
+            slice[indexOf] = newChars[oldChars.IndexOf(chr)];
+            slice = slice[(indexOf + 1)..];
+        }
+    }
+
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public void Replace(char oldChar, char newChar, int startIndex, int count)
+    {
+        int currentLength = _length;
+        if ((uint)startIndex > (uint)currentLength)
+        {
+            throw new ArgumentOutOfRangeException(nameof(startIndex));
+        }
+
+        if (count < 0 || startIndex > currentLength - count)
+        {
+            throw new ArgumentOutOfRangeException(nameof(count));
+        }
+
+        var slice = _chars;
+
+        while (true)
+        {
+            var indexOf = slice.IndexOf(oldChar);
+            if (indexOf == -1)
+            {
+                break;
+            }
+
+            slice[indexOf] = newChar;
+            slice = slice[(indexOf + 1)..];
+        }
+    }
+
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public void Remove(int startIndex, int length)
+    {
+        if (length < 0)
+        {
+            throw new ArgumentOutOfRangeException(nameof(length));
+        }
+
+        if (startIndex < 0)
+        {
+            throw new ArgumentOutOfRangeException(nameof(startIndex));
+        }
+
+        if (length > _length - startIndex)
+        {
+            throw new ArgumentOutOfRangeException(nameof(length));
+        }
+
+        if (startIndex == 0)
+        {
+            _chars = _chars[length..];
+        }
+        else if (startIndex + length == _length)
+        {
+            _chars = _chars[..startIndex];
+        }
+        else
+        {
+            // Somewhere in the middle, this will be slow
+            _chars[(startIndex + length)..].CopyTo(_chars[startIndex..]);
+        }
+
+        _length -= length;
+    }
 }