feat: Upgrades serialization v4 (Threaded Heap Serialization) (#1947)

### Summary

- `GenericEntityPersistence` is now a type of `GenericPersistence`. This allows developers to serialize both entities and non-entities in the same system. 🎉
- Each `SerializationThreadWorker` now allocates 1MB of heap for serialization _permanently_. If more memory is needed, that thread will double it's memory, not to exceed increments of 64MB.
- Several bugs with serialization introduced with the pure MMF implementation have been fixed.
- `BinaryFileReader` has been added back. 🎉
- Adds `world.useMultithreadedSaves` to allow disabling threaded saves.

> [!IMPORTANT]
> **Developer Note**
> The split file serialization has been deprecated and is no longer used. We have effectively gone back to the same file writing we had before the pure MMF implementation.

Projects/Server.Tests/Tests/Network/Packets/Outgoing/AccountPacketTests.cs

@@ -51,6 +51,10 @@ public Mobile this[int index]
         public Serial Serial { get; }
         public void Deserialize(IGenericReader reader) => throw new NotImplementedException();
 
+        public byte SerializedThread { get; set; }
+        public int SerializedPosition { get; set; }
+        public int SerializedLength { get; set; }
+
         public void Serialize(IGenericWriter writer) => throw new NotImplementedException();
 
         public bool Deleted { get; }

Projects/Server/Guild.cs

@@ -52,6 +52,10 @@ protected BaseGuild()
     [CommandProperty(AccessLevel.GameMaster, readOnly: true)]
     public DateTime Created { get; set; } = Core.Now;
 
+    public byte SerializedThread { get; set; }
+    public int SerializedPosition { get; set; }
+    public int SerializedLength { get; set; }
+
     public abstract void Serialize(IGenericWriter writer);
 
     public abstract void Deserialize(IGenericReader reader);

Projects/Server/IEntity.cs

@@ -115,6 +115,10 @@ public void Deserialize(IGenericReader reader)
         Timer.StartTimer(Delete);
     }
 
+    public byte SerializedThread { get; set; }
+    public int SerializedPosition { get; set; }
+    public int SerializedLength { get; set; }
+
     public void Serialize(IGenericWriter writer)
     {
     }

Projects/Server/Items/Item.cs

@@ -802,6 +802,10 @@ public virtual void GetProperties(IPropertyList list)
     [CommandProperty(AccessLevel.Counselor)]
     public Serial Serial { get; }
 
+    public byte SerializedThread { get; set; }
+    public int SerializedPosition { get; set; }
+    public int SerializedLength { get; set; }
+
     public virtual void Serialize(IGenericWriter writer)
     {
         writer.Write(9); // version

Projects/Server/Mobiles/Mobile.cs

@@ -2277,6 +2277,10 @@ public virtual void GetProperties(IPropertyList list)
     [CommandProperty(AccessLevel.Counselor)]
     public Serial Serial { get; }
 
+    public byte SerializedThread { get; set; }
+    public int SerializedPosition { get; set; }
+    public int SerializedLength { get; set; }
+
     public virtual void Serialize(IGenericWriter writer)
     {
         writer.Write(36); // version

Projects/Server/Serialization/AdhocPersistence.cs

@@ -55,8 +55,8 @@ public static void SerializeAndSnapshot(
     {
         var fullPath = PathUtility.GetFullPath(filePath, Core.BaseDirectory);
         PathUtility.EnsureDirectory(Path.GetDirectoryName(fullPath));
-        ConcurrentQueue<Type> types = [];
-        var writer = new MemoryMapFileWriter(new FileStream(filePath, FileMode.Create), sizeHint, types);
+        HashSet<Type> typesSet = [];
+        var writer = new MemoryMapFileWriter(new FileStream(filePath, FileMode.Create), sizeHint, typesSet);
         serializer(writer);
 
         Task.Run(
@@ -67,14 +67,6 @@ public static void SerializeAndSnapshot(
                 writer.Dispose();
                 fs.Dispose();
 
-                HashSet<Type> typesSet = [];
-
-                // Dedupe the queue.
-                foreach (var type in types)
-                {
-                    typesSet.Add(type);
-                }
-
                 Persistence.WriteSerializedTypesSnapshot(Path.GetDirectoryName(fullPath), typesSet);
             },
             Core.ClosingTokenSource.Token

Projects/Server/Serialization/BinaryFileReader.cs

@@ -0,0 +1,109 @@
+/*************************************************************************
+ * ModernUO                                                              *
+ * Copyright 2019-2024 - ModernUO Development Team                       *
+ * Email: [email protected]                                                *
+ * File: BinaryFileReader.cs                                             *
+ *                                                                       *
+ * This program is free software: you can redistribute it and/or modify  *
+ * it under the terms of the GNU General Public License as published by  *
+ * the Free Software Foundation, either version 3 of the License, or     *
+ * (at your option) any later version.                                   *
+ *                                                                       *
+ * You should have received a copy of the GNU General Public License     *
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>. *
+ *************************************************************************/
+
+using System;
+using System.IO;
+using System.IO.MemoryMappedFiles;
+using System.Runtime.CompilerServices;
+using System.Text;
+
+namespace Server;
+
+public sealed unsafe class BinaryFileReader : IDisposable, IGenericReader
+{
+    private readonly bool _usePrefixes;
+    private readonly MemoryMappedFile _mmf;
+    private readonly MemoryMappedViewStream _accessor;
+    private readonly UnmanagedDataReader _reader;
+
+    public BinaryFileReader(string path, bool usePrefixes = true, Encoding encoding = null)
+    {
+        _usePrefixes = usePrefixes;
+        var fi = new FileInfo(path);
+
+        if (fi.Length > 0)
+        {
+            _mmf = MemoryMappedFile.CreateFromFile(path, FileMode.Open);
+            _accessor = _mmf.CreateViewStream();
+            byte* ptr = null;
+            _accessor.SafeMemoryMappedViewHandle.AcquirePointer(ref ptr);
+            _reader = new UnmanagedDataReader(ptr, _accessor.Length, encoding: encoding);
+        }
+        else
+        {
+            _reader = new UnmanagedDataReader(null, 0, encoding: encoding);
+        }
+    }
+
+    public long Position => _reader.Position;
+
+    public void Dispose()
+    {
+        _accessor?.SafeMemoryMappedViewHandle.ReleasePointer();
+        _accessor?.Dispose();
+        _mmf?.Dispose();
+    }
+
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public string ReadString(bool intern = false) => _usePrefixes ? _reader.ReadString(intern) : _reader.ReadStringRaw(intern);
+
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public string ReadStringRaw(bool intern = false) => _reader.ReadStringRaw(intern);
+
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public long ReadLong() => _reader.ReadLong();
+
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public ulong ReadULong() => _reader.ReadULong();
+
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public int ReadInt() => _reader.ReadInt();
+
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public uint ReadUInt() => _reader.ReadUInt();
+
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public short ReadShort() => _reader.ReadShort();
+
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public ushort ReadUShort() => _reader.ReadUShort();
+
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public double ReadDouble() => _reader.ReadDouble();
+
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public float ReadFloat() => _reader.ReadFloat();
+
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public byte ReadByte() => _reader.ReadByte();
+
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public sbyte ReadSByte() => _reader.ReadSByte();
+
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public bool ReadBool() => _reader.ReadBool();
+
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public Serial ReadSerial() => _reader.ReadSerial();
+
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public Type ReadType() => _reader.ReadType();
+
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public int Read(Span<byte> buffer) => _reader.Read(buffer);
+
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public long Seek(long offset, SeekOrigin origin) => _reader.Seek(offset, origin);
+}

Projects/Server/Serialization/BufferWriter.cs

@@ -105,13 +105,7 @@ public void Resize(int size)
         _buffer = newBuffer;
     }
 
-    public virtual void Flush()
-    {
-        // Need to avoid buffer.Length = 2, buffer * 2 is 4, but we need 8 or 16bytes, causing an exception.
-        // The least we need is 16bytes + Index, but we use BufferSize since it should always be big enough for a single
-        // non-dynamic field.
-        Resize(Math.Max(BufferSize, _buffer.Length * 2));
-    }
+    public virtual void Flush() => Resize(Math.Clamp(_buffer.Length * 2, BufferSize, _buffer.Length + 1024 * 1024 * 64));
 
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
     private void FlushIfNeeded(int amount)