Acta. Durable execution for .NET

learn actacontrol order and load

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.

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

Checked every release learn/200-durable-execution/223-lane-per-customer
Read as

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.

lane-per-customer.csexcerpt
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.

lane-per-customer.csexcerpt
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:

Terminal
dotnet run --project learn/200-durable-execution/223-lane-per-customer
Its output must contain
customer a applied: 1, 2, 3
customer b applied: 1, 2, 3
customers side by side: yes

Checked 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 blocked until 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
lane-per-customer.cs
// 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);
        }
    }
}

Where to go next

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.