modernuo/dev-docs/threading-model.md

ModernUO Threading Model

This document covers ModernUO's single-threaded game loop architecture, the EventLoopContext synchronization context, memory pooling, and rules for safe concurrent code.

Core Principle: Single-Threaded Game Logic

All game logic in ModernUO runs on a single thread. There are no exceptions for code under Projects/UOContent/.

This means:

• No locks, mutexes, or synchronization primitives needed
• No concurrent collections needed
• No volatile fields needed
• No race conditions possible in game code
• await is safe because continuations route through EventLoopContext

Game Loop

The game loop in Projects/Server/Main.cs runs continuously:

public static void RunEventLoop()
{
    while (!Closing)
    {
        _tickCount = GetTimestamp();
        _now = DateTime.UtcNow;

        Mobile.ProcessDeltaQueue();    // Send mobile state changes to clients
        Item.ProcessDeltaQueue();      // Send item state changes to clients
        Timer.Slice(_tickCount);       // Execute due timers
        NetState.Slice();              // Process network I/O
        LoopContext.ExecuteTasks();     // Run async continuations
        Timer.CheckTimerPool();        // Refill timer pool if needed

        // World save handling
        if (_performSnapshot)
        {
            World.Snapshot(_snapshotPath);
            _performSnapshot = false;
        }
    }
}

Each iteration:

1. Updates timestamp
2. Sends pending mobile/item updates to clients
3. Fires due timers
4. Processes incoming network packets
5. Runs async continuations (from await)
6. Checks timer pool health
7. Handles world save snapshots if requested

EventLoopContext

EventLoopContext implements SynchronizationContext to ensure all await continuations run on the game thread.

Defined in Projects/Server/EventLoopTasks.cs:

public sealed class EventLoopContext : SynchronizationContext
{
    public enum Priority { Normal, High }

    private readonly ConcurrentQueue<Action> _queue;
    private readonly ConcurrentQueue<Action> _priorityQueue;
    private readonly Thread _mainThread;
    private readonly int _maxPerFrame;  // Default: 128

    // Post: queues action for next ExecuteTasks() call
    public void Post(Action d, Priority priority = Priority.Normal);

    // SynchronizationContext.Post: used by await
    public override void Post(SendOrPostCallback d, object state);

    // Send: immediate if on main thread, blocks if on other thread
    public override void Send(SendOrPostCallback d, object state);

    // Called once per game loop tick
    public void ExecuteTasks();
}

How await Works

// Safe in game code:
await Timer.Pause(TimeSpan.FromMilliseconds(100));
// After the pause, execution continues on the game thread

Flow:

1. await captures EventLoopContext as the current SynchronizationContext
2. When the awaited task completes, the continuation is posted to _queue
3. LoopContext.ExecuteTasks() runs the continuation on the main thread
4. Game state is safely accessible

Task Limits

• Maximum 128 tasks per frame by default (configurable)
• High-priority tasks (_priorityQueue) are always processed first
• Normal tasks are processed up to the per-frame limit

Forbidden Patterns

In Game Code (Projects/UOContent/)

Pattern	Problem	Alternative
Task.Run(...)	Runs on thread pool, races with game state	Timer.StartTimer()
new Thread(...)	Manual thread, races with game state	Timer.StartTimer()
ThreadPool.QueueUserWorkItem(...)	Thread pool, same issue	Timer.StartTimer()
lock(obj) { ... }	Unnecessary overhead, no contention	Remove lock
Monitor.Enter(obj)	Same as lock	Remove
volatile int _field	Memory barriers not needed	Plain field
ConcurrentDictionary<K,V>	Lock-free overhead, unnecessary	Dictionary<K,V>
ConcurrentQueue<T>	Same	Queue<T> or List<T>
ConcurrentBag<T>	Same	List<T>
Interlocked.Increment(...)	Atomic operations unnecessary	_field++
Mutex / Semaphore	OS-level sync, unnecessary	Remove
ReaderWriterLockSlim	Lock overhead, unnecessary	Remove
Thread.Sleep(ms)	Blocks entire game loop	await Timer.Pause(ms)

Exceptions: Server Infrastructure

These files in Projects/Server/ MAY use threading because they handle I/O outside the game loop:

• Main.cs -- Event loop setup, thread configuration
• World/World.cs -- World save disk I/O (serialization on main thread, writes on background)
• Network/ -- Network I/O processing
• Timer/Timer.Pool.cs -- Async pool refill
• EventLoopTasks.cs -- The synchronization context itself

Memory Pooling

STArrayPool

Single-threaded array pool optimized for game code (no locks):

// Defined in Projects/Server/Buffers/STArrayPool.cs
public class STArrayPool<T> : ArrayPool<T>
{
    public static new STArrayPool<T> Shared { get; }

    public override T[] Rent(int minimumLength);
    public override void Return(T[]? array, bool clearArray = false);
}

Usage:

var buffer = STArrayPool<byte>.Shared.Rent(1024);
try
{
    // Use buffer (may be larger than requested)
}
finally
{
    STArrayPool<byte>.Shared.Return(buffer);
}

Architecture:

• 27 buckets covering sizes 16 to 1GB+
• Per-bucket cache (1 array) + stack storage (32 arrays)
• Trim callbacks on Gen2 GC to reduce memory pressure
• Formula: bucket index = Log2(size - 1 | 15) - 3

Use STArrayPool<T>.Shared in game code, not ArrayPool<T>.Shared (which uses locks).

PooledRefList

Stack-allocated list using pooled arrays:

// Defined in Projects/Server/Collections/PooledRefList.cs
public ref struct PooledRefList<T>
{
    public static PooledRefList<T> Create(int capacity = 32, bool mt = false);
    public static PooledRefList<T> CreateMT(int capacity = 32);  // Multi-threaded

    public void Add(T item);
    public bool Remove(T item);
    public void Clear();
    public int Count { get; }
    public T this[int index] { get; set; }
    public void Dispose();  // Returns array to pool
}

Usage:

using var list = PooledRefList<Mobile>.Create();
list.Add(mobile);
// list is stack-allocated, zero GC pressure
// Dispose() returns backing array to STArrayPool

Key properties:

• ref struct -- stack-allocated, cannot escape to heap
• Uses STArrayPool<T> by default, ArrayPool<T>.Shared with CreateMT()
• Auto-grows when capacity exceeded
• Must be disposed (use using pattern)

World Save Threading

World saves involve both threads:

1. World.Save() -- Called on main thread, queues preserialize to thread pool
2. Preserialize() -- Thread pool: allocates serialization heaps, wakes workers
3. Snapshot() -- Main thread: serializes all game state (safe access), blocks game loop briefly
4. WriteFiles() -- Thread pool: writes serialized data to disk (no game state access)

Main Thread:    Save() → ... → Snapshot() → ... → continue loop
Thread Pool:    Preserialize() → ... → WriteFiles()

The main thread blocks during Snapshot() to ensure consistent state, then the disk I/O happens asynchronously.

Best Practices

1. Never use concurrency primitives in game code -- they add overhead for no benefit
2. Use STArrayPool<T>.Shared instead of ArrayPool<T>.Shared
3. Use PooledRefList<T> instead of new List<T>() in hot paths
4. Use await Timer.Pause() instead of Thread.Sleep()
5. Use Timer.StartTimer() instead of Task.Run() for delayed work
6. Trust single-threaded invariants -- no need to protect shared state

Key File References

File	Description
Projects/Server/Main.cs	Game loop (RunEventLoop)
Projects/Server/EventLoopTasks.cs	EventLoopContext
Projects/Server/Buffers/STArrayPool.cs	Single-threaded array pool
Projects/Server/Collections/PooledRefList.cs	Pooled ref list
Projects/Server/World/World.cs	World save system