LogicLooper.Diagnostics 1.7.0

LogicLooper

日本語

A library is for building server application using loop-action programming model on .NET. This library focuses on building game servers with server-side logic.

For example, if you have the following game loops, the library will provide a way to aggregate and process in a more efficient way than driving with a simple Task.

while (true)
{
    // some stuff to do ...
    network.Receive();
    world.Update();
    players.Update();
    network.Send();
    // some stuff to do ...

    // wait for next frame
    await Task.Delay(16);
}

using var looper = new LogicLooper(60);
await looper.RegisterActionAsync((in LogicLooperActionContext ctx) =>
{
    // The action will be called by looper every frame.
    // some stuff to do ...
    network.Receive();
    world.Update();
    players.Update();
    network.Send();
    // some stuff to do ...

    return true; // wait for next update
});

Table of Contents

• Installation
• Usage
  • Single-loop application
  • Multiple-loop application using LooperPool
  • Integrate with Microsoft.Extensions.Hosting
  • Metrics
• Advanced
  • Unit tests / Frame-by-Frame execution
  • Coroutine
  • TargetFrameRateOverride
• Experimental
  • async-aware loop actions

Installation

PS> Install-Package LogicLooper

$ dotnet add package LogicLooper

Usage

Single-loop application

A Looper bound one thread and begin a main-loop. You can register multiple loop actions for the Looper. It's similar to be multiple Update methods called in one frame of the game engine.

using Cysharp.Threading;

// Create a looper.
const int targetFps = 60;
using var looper = new LogicLooper(targetFps);

// Register a action to the looper and wait for completion.
await looper.RegisterActionAsync((in LogicLooperActionContext ctx) =>
{
    // If you want to stop/complete the loop, return false to stop.
    if (...) { return false; }

    // some stuff to do ...

    return true; // wait for a next update.
});

Multiple-loop application using LooperPool

For example, if your server has many cores, it is more efficient running multiple loops. LooperPool provides multiple loopers and facade for using them.

using Cysharp.Threading;

// Create a looper pool.
// If your machine has 4-cores, the LooperPool creates 4-Looper instances.
const int targetFps = 60;
var looperCount = Environment.ProcessorCount;
using var looperPool = new LogicLooperPool(targetFps, looperCount, RoundRobinLogicLooperPoolBalancer.Instance);

// Register a action to the looper and wait for completion.
await looperPool.RegisterActionAsync((in LogicLooperActionContext ctx) =>
{
    // If you want to stop/complete the loop, return false to stop.
    if (...) { return false; }

    // some stuff to do ...

    return true; // wait for a next update.
});

Integrate with Microsoft.Extensions.Hosting

See samples/LoopHostingApp.

Metrics

LogicLooper provides metrics using the Metric API. This allows you to obtain the number of LogicLoopers and registered actions, as well as the execution time per loop.

To enable metrics collection, install the LogicLooper.Diagnostics package and call AddLogicLooperMetrics.

services.AddLogicLooperMetrics();

LogicLooper.processing_duration records the time spent processing each frame, excluding the time spent waiting for the next frame. Every frame is recorded, including frames in which no action is invoked, for example because no action is registered or all actions are skipped by TargetFrameRateOverride. Such frames take very little time, so the average tends to be small when they are frequent. To find heavy frames, look at the distribution, such as percentiles or the maximum, rather than the average.

LogicLooper.processing_duration provides the following explicit bucket boundaries in seconds through InstrumentAdvice. They include the frame times of 60 fps (1/60) and 30 fps (1/30), so you can count the frames that exceed them. You can override the boundaries with the configuration of your metrics SDK, such as a view in OpenTelemetry.

0.0001, 0.00025, 0.0005, 0.00075, 0.001, 0.0025, 0.005, 0.0075, 0.01, 1/60, 0.025, 1/30, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1

If a MeterListener callback throws an exception while LogicLooper.processing_duration is recorded, the exception is ignored without being reported, so that it does not escape the loop thread and terminate the process. In that case, the other listeners of the same instrument may also miss the measurement.

LogicLooper.processing_duration has the following tag.

Advanced

Unit tests / Frame-by-Frame execution

If you want to write unit tests with LogicLooper or update frames manually, you can use ManualLogicLooper / ManualLogicLooperPool.

var looper = new ManualLogicLooper(60.0); // `ElapsedTimeFromPreviousFrame` will be fixed to `1000 / FrameTargetFrameRate`.

var count = 0;
var t1 = looper.RegisterActionAsync((in LogicLooperActionContext ctx) =>
{
    count++;
    return count != 3;
});

looper.Tick(); // Update frame
Console.WriteLine(count); // => 1

looper.Tick(); // Update frame
Console.WriteLine(count); // => 2

looper.Tick(); // Update frame (t1 will be completed)
Console.WriteLine(count); // => 3

looper.Tick(); // Update frame (no action)
Console.WriteLine(count); // => 3

Coroutine

LogicLooper has support for the coroutine-like operation. If you are using Unity, you are familiar with the coroutine pattern.

using var looper = new LogicLooper(60);

var coroutine = default(LogicLooperCoroutine);
await looper.RegisterActionAsync((in LogicLooperActionContext ctx) =>
{
    if (/* ... */)
    {
        // Launch a coroutine in the looper that same as the loop action.
        coroutine = ctx.RunCoroutine(async coCtx =>
        {
            // NOTE: `DelayFrame`, `DelayNextFrame`, `Delay` methods are allowed and awaitable in the coroutine.
            // If you await a Task or Task-like, the coroutine throws an exception.
            await coCtx.DelayFrame(60);

            // some stuff to do ...

            await coCtx.DelayNextFrame();

            // some stuff to do ...

            await coCtx.Delay(TimeSpan.FromMilliseconds(16.66666));
        });
    }

    if (coroutine.IsCompleted)
    {
        // When the coroutine has completed, you can do some stuff ...
    }

    return true;
});

TargetFrameRateOverride

TargetFrameRateOverride option allows to override the frame rate for each action. This can be useful in cases where you want to mix multiple frame rates, such as expecting the main loop to run at 30fps, but wanting some actions to be called at 5fps.

You can also set the frame rate for each Looper that executes the loops, but the design of LogicLooper is 1-loop per thread, so in principle we expect a number of Loopers in accordance with the number of cores. By setting the frame rate for each action, you can keep the number of Loopers fixed even if the workload changes.

using var looper = new LogicLooper(60); // 60 fps

await looper.RegisterActionAsync((in LogicLooperActionContext ctx) =>
{
    // Something to do ...
    return true;
}); // The action will be called at 60fps.

await looper.RegisterActionAsync((in LogicLooperActionContext ctx) =>
{
    // Something to do (low priority) ...
    return true;
}, LooperActionOptions.Default with { TargetFrameRateOverride = 10 }); // The action will be called at 10fps.

The granularity of action execution changes based on the execution frequency of the main loop itself. This means that the accuracy may be inferior to the target frame rate of the Looper.

Experimental

async-aware loop actions

Experimental support for loop actions that can await asynchronous events.

With SynchronizationContext, all asynchronous continuations are executed on the loop thread. Please beware that asynchronous actions are executed across multiple frames, unlike synchronous actions.

await looper.RegisterActionAsync(static async (ctx, state) =>
{
    state.Add("1"); // Frame: 1
    await Task.Delay(250);
    state.Add("2"); // Frame: 2 or later
    return false;
});