Acta. Durable execution for .NET

learn actadeploy and scale

How to set how many jobs a worker runs at once

MaxConcurrentExecutors caps how many jobs one worker runs at once, and SafetyPollInterval bounds how long an idle worker sleeps between looks at the database.

A how-to for Acta, durable execution for .NET. New to Acta? Run your first durable job in five minutes.

Checked every release learn/900-runtime-and-tuning/904-worker-tuning
Read as

1Cap how many jobs the worker runs at once

Cap simultaneous in-flight executions at Cap. Each claim takes only as many rows as there are free executors, so excess work stays Ready in the database until an executor frees. Fixed at startup; not autoscaled. The program sets Cap to 3.

worker-tuning.csexcerpt
builder.Services.UseActa(j =>
{
    j.UseLocalDatabase(builder.Configuration);

    j.ConfigureOptions(o =>
    {
        o.MaxConcurrentExecutors = Cap;

        o.SafetyPollInterval = TimeSpan.FromSeconds(1);
    });

    j.Run<WorkerTuningJobs>("worker-tuning");
});

2Bound how long an idle worker sleeps

Upper bound on idle claim-loop sleep. 1s is the default and the minimum (the validator rejects lower values as a DB-traffic guard). An enqueue wakes the worker at once, so the interval only matters for work nothing announced.

worker-tuning.csexcerpt
builder.Services.UseActa(j =>
{
    j.UseLocalDatabase(builder.Configuration);

    j.ConfigureOptions(o =>
    {
        o.MaxConcurrentExecutors = Cap;

        o.SafetyPollInterval = TimeSpan.FromSeconds(1);
    });

    j.Run<WorkerTuningJobs>("worker-tuning");
});

3The job it acts on

worker-tuning.csexcerpt
public static int Completed => Volatile.Read(ref _completed);
public static int PeakConcurrency => Volatile.Read(ref _peak);

// Each handler holds its executor for 50 ms - long enough that Cap parallel handlers
// overlap and the peak counter exceeds 1.
[Job("slow-task")]
public static async Task Handle(SlowTask input, CancellationToken ct)
{
    // Increment active count; update peak if this is a new high.
    var active = Interlocked.Increment(ref _active);
    int peak;
    do
    {
        peak = Volatile.Read(ref _peak);
        if (active <= peak)
            break;
    } while (Interlocked.CompareExchange(ref _peak, active, peak) != peak);

    Console.WriteLine($"[{input.Id}] started (active={active})");

    await Task.Delay(50, ct);

    Interlocked.Decrement(ref _active);
    Interlocked.Increment(ref _completed);
    Console.WriteLine($"[{input.Id}] done");
}

4Run it and check the output

From a clone of the Acta repository, with the .NET 10 SDK:

Terminal
dotnet run --project learn/900-runtime-and-tuning/904-worker-tuning
Its output must contain
Peak observed concurrency: 3 (cap=3).
Concurrency cap respected: True

Checked every release. Before each release, Acta Verify runs this program and checks that its output contains these lines.

This page shows the code. The rules it relies on, starting with the handler running again from its first line, are in the handler contract.

The whole program

Every file of learn/900-runtime-and-tuning/904-worker-tuning, as it is compiled.

UseLocalDatabase is a helper of the Acta repository, not of the packages. In your own app, register the database with UseSqlite, UsePostgres or UseSqlServer, as in how to run your first job.

worker-tuning.cs104 lines
worker-tuning.cs
// How to set how many jobs a worker runs at once
// `MaxConcurrentExecutors` caps how many jobs one worker runs at once, and `SafetyPollInterval` bounds how long an
// idle worker sleeps between looks at the database.
using Acta;
using Acta.Learn.WorkerTuning;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

const int Cap = 3;

var builder = Host.CreateApplicationBuilder(args);

builder.Services.UseActa(j =>
{
    j.UseLocalDatabase(builder.Configuration);

    j.ConfigureOptions(o =>
    {
        // learn: 1. Cap how many jobs the worker runs at once
        // Cap simultaneous in-flight executions at Cap. Each claim takes only as many rows as there are
        // free executors, so excess work stays Ready in the database until an executor frees. Fixed at startup;
        // not autoscaled. The program sets `Cap` to 3.
        o.MaxConcurrentExecutors = Cap;
        // learn: end

        // learn: 2. Bound how long an idle worker sleeps
        // Upper bound on idle claim-loop sleep. 1s is the default and the minimum (the validator rejects
        // lower values as a DB-traffic guard). An enqueue wakes the worker at once, so the interval only
        // matters for work nothing announced.
        o.SafetyPollInterval = TimeSpan.FromSeconds(1);
        // learn: end
    });

    j.Run<WorkerTuningJobs>("worker-tuning");
});

using var host = builder.Build();
await host.StartAsync();

var jobs = host.Services.GetRequiredService<IJobs>();

// Enqueue a batch; the wakeup signal fires as soon as the first claim poll reads them.
const int BatchSize = 12;
var requests = Enumerable
    .Range(1, BatchSize)
    .Select(i => new EnqueueJobRequest("worker-tuning", "slow-task", JobPayload.Json(new SlowTask(i))))
    .ToList();

Console.WriteLine($"Enqueuing {BatchSize} jobs (cap={Cap})...");
await jobs.EnqueueJobsAsync(requests);
Console.WriteLine("Batch enqueued. Worker is draining.");

// Wait until all jobs have run; the handler increments/decrements a counter so we can observe
// the peak concurrency without any intrusion into the framework internals.
while (SlowTaskJob.Completed < BatchSize)
{
    await Task.Delay(50);
}

Console.WriteLine($"All {BatchSize} jobs done. Peak observed concurrency: {SlowTaskJob.PeakConcurrency} (cap={Cap}).");
Console.WriteLine($"Concurrency cap respected: {SlowTaskJob.PeakConcurrency <= Cap}");

await host.StopAsync();

namespace Acta.Learn.WorkerTuning
{
    public sealed record SlowTask(int Id);

    public static class SlowTaskJob
    {
        // Active tracks simultaneous in-flight handlers; Completed counts finished ones.
        // Both are updated atomically so the peak observation is race-free.
        private static int _active;
        private static int _completed;
        private static int _peak;

        public static int Completed => Volatile.Read(ref _completed);
        public static int PeakConcurrency => Volatile.Read(ref _peak);

        // Each handler holds its executor for 50 ms - long enough that Cap parallel handlers
        // overlap and the peak counter exceeds 1.
        [Job("slow-task")]
        public static async Task Handle(SlowTask input, CancellationToken ct)
        {
            // Increment active count; update peak if this is a new high.
            var active = Interlocked.Increment(ref _active);
            int peak;
            do
            {
                peak = Volatile.Read(ref _peak);
                if (active <= peak)
                    break;
            } while (Interlocked.CompareExchange(ref _peak, active, peak) != peak);

            Console.WriteLine($"[{input.Id}] started (active={active})");

            await Task.Delay(50, ct);

            Interlocked.Decrement(ref _active);
            Interlocked.Increment(ref _completed);
            Console.WriteLine($"[{input.Id}] done");
        }
    }
}

New to Acta?

Acta is durable execution for .NET: workflows and jobs that survive restarts, as a library inside your application with its durable state in your SQL database.