1Name the customer's lane when you enqueue
The jobs of one lane run one at a time, in the order they were enqueued. Each customer has a lane of its own, so a slow command holds back that customer's next commands and nobody else's.
var commands = new List<JobHandle>();
foreach (var number in new[] { 1, 2, 3 })
{
foreach (var customer in customers)
{
commands.Add(await jobs.EnqueueAsync(new ApplyCommand(customer, number), o => o.Lane($"customer-{customer}")));
}
}2Let the first command be the slow one
Each customer's first command takes the longest. Without the lane the second and the third would be applied before it.
public static class ApplyCommandJob
{
[Job("apply-command")]
public static async Task Handle(ApplyCommand command, CancellationToken ct)
{
Applied.Started();
await Task.Delay(command.Number == 1 ? 400 : 50, ct);
Applied.Finished(command);
}
}3Run it and check the output
From a clone of the Acta repository, with the .NET 10 SDK:
dotnet run --project learn/200-durable-execution/223-lane-per-customercustomer a applied: 1, 2, 3
customer b applied: 1, 2, 3
customers side by side: yesChecked every release. Before each release, Acta Verify runs this program and checks that its output contains these lines.
Remember
- One job of a lane runs at a time, in enqueue order. The jobs behind the head read
blockeduntil it finishes: succeeded, failed on its last attempt, or cancelled. - A failing head keeps retrying in place and holds the lane. A paused head holds it until it is resumed.
- A head whose worker died holds the lane until recovery reclaims it: three to about seven minutes at the default heartbeat.
- A lane is order, not a condition: the next job runs after a failed or a cancelled head too.
[Job("sync-orders", Lane = "orders")]on a definition puts every job of that definition in one lane.- A concurrency key keeps jobs from overlapping and promises no order: an older job can be overtaken while the key is busy. Limit how many jobs run at once for one key shows it.
Check yourself
Customer a's first command fails and is retried. What happens to a's second command meanwhile?
Show the answer
It stays blocked until the first one finishes. A failing head keeps retrying in place and holds its lane, so the order holds across retries. Customer b's lane is not touched by it.
The whole program
Every file of learn/200-durable-execution/223-lane-per-customer, 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.
lane-per-customer.cs101 lines
// How to apply each customer's commands in order while other customers keep moving
// A lane runs its jobs one at a time, in enqueue order. A lane per customer keeps each customer's commands in order
// and lets the customers run side by side.
using Acta;
using Acta.Learn.LanePerCustomer;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
var builder = Host.CreateApplicationBuilder(args);
builder.Services.UseActa(j =>
{
j.UseLocalDatabase(builder.Configuration);
j.Run<LanePerCustomerJobs>("lane-per-customer");
});
using var host = builder.Build();
await host.StartAsync();
var jobs = host.Services.GetRequiredService<IJobs>();
string[] customers = ["a", "b"];
var commands = new List<JobHandle>();
foreach (var number in new[] { 1, 2, 3 })
{
foreach (var customer in customers)
{
// learn: 1. Name the customer's lane when you enqueue
// The jobs of one lane run one at a time, in the order they were enqueued. Each customer has a lane of its
// own, so a slow command holds back that customer's next commands and nobody else's.
commands.Add(await jobs.EnqueueAsync(new ApplyCommand(customer, number), o => o.Lane($"customer-{customer}")));
// learn: end
}
}
foreach (var command in commands)
{
await command.WaitAsync();
}
foreach (var customer in customers)
{
Console.WriteLine($"customer {customer} applied: {string.Join(", ", Applied.By(customer))}");
}
Console.WriteLine($"customers side by side: {(Applied.MostAtOnce > 1 ? "yes" : "no")}");
await host.StopAsync();
namespace Acta.Learn.LanePerCustomer
{
public sealed record ApplyCommand(string Customer, int Number);
/// <summary>What the handlers did, for the program to print: the order per customer and how many ran at once.</summary>
public static class Applied
{
private static readonly List<ApplyCommand> Commands = [];
private static int _running;
public static int MostAtOnce { get; private set; }
public static int[] By(string customer)
{
lock (Commands)
{
return Commands.Where(c => c.Customer == customer).Select(c => c.Number).ToArray();
}
}
public static void Started()
{
lock (Commands)
{
MostAtOnce = Math.Max(MostAtOnce, ++_running);
}
}
public static void Finished(ApplyCommand command)
{
lock (Commands)
{
Commands.Add(command);
_running--;
}
}
}
public static class ApplyCommandJob
{
[Job("apply-command")]
public static async Task Handle(ApplyCommand command, CancellationToken ct)
{
Applied.Started();
// learn: 2. Let the first command be the slow one
// Each customer's first command takes the longest. Without the lane the second and the third would be
// applied before it.
await Task.Delay(command.Number == 1 ? 400 : 50, ct);
// learn: end
Applied.Finished(command);
}
}
}