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.
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.
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
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:
dotnet run --project learn/900-runtime-and-tuning/904-worker-tuningPeak observed concurrency: 3 (cap=3).
Concurrency cap respected: TrueChecked 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
// 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");
}
}
}