JobDispatcherNET.Extensions.Logging 0.11.0

JobDispatcherNET

Lock-free actor-style job dispatcher for .NET game servers. Each object owns a job queue. Work on one object is serialized without locks; different objects run fully in parallel, on dedicated OS threads.

한국어 문서: README.ko.md · 전체 가이드: Book/

packet: player A "move"    → actorA.DoAsync(Move)   ─┐
packet: player B "move"    → actorB.DoAsync(Move)   ─┼─ fully parallel
packet: player C "hit A"   → actorC.DoAsync(Snapshot) → actorA.DoAsync(TakeDamage)

30-second example

using JobDispatcherNET;

public sealed class PlayerActor : AsyncExecutable
{
    private int _hp = 100;   // no lock, ever

    public void TakeDamage(int amount) =>
        DoAsync(static t => t.Self.Apply(t.Amount), (Self: this, Amount: amount));

    private void Apply(int amount)
    {
        _hp -= amount;                       // only one thread is ever in here
        if (_hp <= 0) DoAsyncAfter(TimeSpan.FromSeconds(5), Respawn);
    }

    private void Respawn() => _hp = 100;
}

// Start a pool of dedicated OS worker threads.
using var dispatcher = new JobDispatcher(workerCount: 8);
_ = dispatcher.RunWorkerThreadsAsync();

var player = new PlayerActor();
player.TakeDamage(10);                       // safe to call from any thread

// Graceful shutdown: drain everything in flight, then stop.
await JobSystem.Default.StopAsync(TimeSpan.FromSeconds(10));

Install:

dotnet add package JobDispatcherNET

Why this instead of the obvious alternatives

ActionBlock<T> with MaxDegreeOfParallelism = 1 gives you the same serialization guarantee, and for many programs it is the right answer. This library exists because a game server tends to want four other things at the same time:

Don't use this if: you need actors across more than one process (use Orleans), you have a straight data-flow pipeline (use TPL Dataflow), or nearly every one of your jobs is an await on a database — a thread-pool design fits that better, though AsyncReentrancy handles it if you need to mix the two.

What you get

• Serialization without locks — one actor's jobs never overlap, so its fields need no synchronization. How it works.
• Dedicated OS threads — real threads, not thread-pool threads, so long loops and per-thread state are safe. Idle workers block on a signal; there is no polling.
• Allocation-free hot path — DoAsync<TState>(static lambda, state) plus a capped job pool.
• Cancellable and repeating timers — DoAsyncAfter / DoAsyncEvery return an ITimerHandle. One timer thread per system, so a worker crash cannot take your timers with it.
• Back-pressure — MaxQueueSize with a drop callback that tells you why a job was refused.
• Two execution modes — inline (LeaderFlush) for actor-to-actor calls, Scheduled for actors reached from socket or thread-pool threads so they never run game logic on your IO thread.
• async/await support — RunAsync / AskAsync with a choice of interleaved or exclusive re-entrancy; continuations come back onto the actor.
• Request/response — Ask returns a Task<T>; AskSync blocks safely and throws if you call it from somewhere that would deadlock.
• Observability — counters, gauges and histograms published through System.Diagnostics.Metrics, so OpenTelemetry and dotnet-counters see them with no wiring.
• Ordering across producers — Sequencer<T> keeps one session's packets in arrival order.
• One-call shutdown — StopAsync drains in-flight work (including work it cascades into), then stops timers and workers.

Core types

Production shape

// One system per pool of actors. Most servers need exactly one.
var system = new JobSystem(new JobSystemOptions
{
    Name = "game",
    Logger = new MicrosoftLoggerAdapter(logger),   // JobDispatcherNET.Extensions.Logging
    MaxJobDuration = TimeSpan.FromMilliseconds(50),
});

using var dispatcher = new JobDispatcher(8, new JobDispatcherOptions { System = system });
_ = dispatcher.RunWorkerThreadsAsync();

public sealed class PlayerActor : AsyncExecutable
{
    public PlayerActor(Player p, JobSystem system) : base(new JobOptions
    {
        Name    = $"Player#{p.Id}",
        System  = system,
        MaxQueueSize = 256,                       // OOM guard
        OnDropped = static (actor, reason) => Log.Warn($"{actor.Name} refused a job: {reason}"),
        MaxConsecutiveFailures = 10,              // quarantine a broken actor
    }) { }

    // Hot path: static lambda + explicit state means no closure allocation.
    public void Move(float x, float y) =>
        DoAsync(static t => t.Self.ProcessMove(t.X, t.Y), (Self: this, X: x, Y: y));
}

// Packets from an IO thread, kept in order, handled on a worker:
// maxPending is this session's back-pressure: unbounded, one fast client is an OOM.
var packets = new Sequencer<string>(system, line => PacketHandler.Handle(session, line),
    onError: null, maxPending: 256);
// ...on the socket thread:
if (!packets.Enqueue(line))
    session.Disconnect("inbound queue full");

// Shutdown.
await system.StopAsync(TimeSpan.FromSeconds(10));

With ASP.NET Core or the Generic Host, JobDispatcherNET.Extensions.Hosting does the wiring:

services.AddJobDispatcher(o => o.WorkerCount = 8);

Documentation

Samples

dotnet run --project samples/AdvancedMmorpgServer      # listens on 25100
# console: status | metrics | q

# Binary-protocol server plus a 200-client load run:
dotnet run -c Release --project samples/PipelinesServer -- --port 25120 --workers 8
dotnet run -c Release --project samples/LoadClient    -- --port 25120 --clients 200 --duration 20

Or start from the template:

dotnet new install JobDispatcherNET.Templates
dotnet new jobdispatcher-server -n MyGameServer

Building and testing

dotnet build All.sln
dotnet test JobDispatcherNET.Tests/JobDispatcherNET.Tests.csproj --filter "Category!=Stress"
dotnet run  -c Release --project JobDispatcherNET.Benchmarks -- --filter *

The library targets net8.0 and net10.0 and has no runtime dependencies.

Contributing

See CONTRIBUTING.md. Concurrency changes need a regression test that fails without the fix — RegressionTests.cs is the model.

Acknowledgements

The execution model — an actor that owns its job queue, with producers electing a flush leader — follows the design of the C++ JobDispatcher by ujentus. The .NET code in this repository is an independent implementation written from that design; no source was translated or copied from it.

License

MIT.