Feature: Incremental Autosave and Chunk IO Read Pool

This feature adds incremental dirty-chunk flushing and optional chunk DB read pooling.

Where It Lives

Main patch:

• patches/VintagestoryLib/Vintagestory.Server/ServerSystemLoadAndSaveGame.cs.patch

Incremental Dirty Flush

On off-thread ticks where a full save is not running, Stratum can perform incremental flushes:

if (!chunkthread.runOffThreadSaveNow)
{
    TryStratumIncrementalDirtyFlush(reusableStream);
    return;
}

The flush path is gated by config and server state:

if (!autoSave.Enabled || !autoSave.IncrementalDirtyFlush || server.RunPhase != EnumServerRunPhase.RunGame || server.Saving || server.Suspended || chunkthread.BackupInProgress)
{
    return;
}

And rate-limited by IncrementalFlushIntervalSeconds.

Scan-Key Refresh and Budgets

Stratum maintains key snapshots and rotating scan indexes:

private readonly List<long> stratumLoadedChunkSaveScanKeys = new List<long>();
private readonly List<long> stratumMapChunkSaveScanKeys = new List<long>();
private int stratumLoadedChunkSaveScanIndex;
private int stratumMapChunkSaveScanIndex;

Loaded chunk flush budget path:

while (scanned < autoSave.MaxLoadedChunkScansPerFlush && saved < autoSave.MaxLoadedChunksPerFlush && stratumLoadedChunkSaveScanKeys.Count > 0)
{
    ...
}

Map chunk flush budget path mirrors this with:

• MaxMapChunkScansPerFlush
• MaxMapChunksPerFlush

Dirty-Flag Safety on Failure

When incremental flush fails, the patch restores dirty flags for chunks that were marked clean before write:

catch (Exception exception)
{
    foreach (ServerChunk chunk in dirtiedChunks)
    {
        chunk.DirtyForSaving = true;
    }

    StratumRuntime.LogWarning("incremental loaded chunk flush failed: " + exception.Message);
    return 0;
}

Equivalent logic exists for map chunks.

Chunk Read Pool

At startup, Stratum can open a read-only chunk DB connection pool:

chunkthread.stratumReadPool = new StratumChunkReadPool(dbFile, ioCfg.WorkerThreads, server.Config.CorruptionProtection);

This runs in TryStartStratumChunkReadPool() and is disposed on separate-thread shutdown.

Stats Hook

Incremental flush activity is reported via:

StratumRuntime.PerformanceStats.RecordIncrementalSaveFlush(...)

Source of Truth

• patches/VintagestoryLib/Vintagestory.Server/ServerSystemLoadAndSaveGame.cs.patch
• sources/VintagestoryLib/Vintagestory.Server/StratumConfig.cs (Performance.AutoSave, Performance.ChunkIo)
• wiki/Performance.md