Acta. Durable execution for .NET

learn actarun work on a schedule

How to give one job several schedules

Several [Schedule] attributes on one job share one permanent job, and schedules that come due together fire it once.

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

Checked every releaseLab learn/100-scheduling/103-multiple-schedules
Read as

1Put several schedules on the one job

Several [Schedule]s share one permanent job; schedules due at the same instant coalesce into ONE execution, and context.TriggeringSchedules reports which fired.

multiple-schedules.csexcerpt
public sealed class ReportJob
{
    [Job("report")]
    [Schedule("fast", "PT10S")]
    [Schedule("faster", "PT5S")]
    public Task Handle(Report input, JobContext context, CancellationToken ct)
    {
        Console.WriteLine(
            $"{DateTime.UtcNow:HH:mm:ss} UTC fired by [{string.Join(", ", context.TriggeringSchedules.Select(s => s.ScheduleName))}]"
        );
        return Task.CompletedTask;
    }
}

2Read which schedules fired this execution

multiple-schedules.csexcerpt
public sealed class ReportJob
{
    [Job("report")]
    [Schedule("fast", "PT10S")]
    [Schedule("faster", "PT5S")]
    public Task Handle(Report input, JobContext context, CancellationToken ct)
    {
        Console.WriteLine(
            $"{DateTime.UtcNow:HH:mm:ss} UTC fired by [{string.Join(", ", context.TriggeringSchedules.Select(s => s.ScheduleName))}]"
        );
        return Task.CompletedTask;
    }
}

3Run it and check the output

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

Terminal
dotnet run --project learn/100-scheduling/103-multiple-schedules
Its output must contain
fired by [faster]
fired by [fast, faster]

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 lab behind it: one permanent job, moving cursors

This program is an Engineering Lab: beside the how-to it prints the rows that show what happened, and its notes weigh the design against the alternatives.

The problem

Row-per-occurrence schedulers make every tick a new durable identity. That preserves independent history, but it also creates unbounded job rows and more duplicate-fire edges.

Common approaches

  • Insert one job for every occurrence.
  • Keep one permanent job and advance schedule cursors.
  • Let an external scheduler enqueue one-shot work.
  • Use an in-process timer and accept process-local availability.

Why this design

Acta stores one reusable job identity and one cursor per schedule. A due schedule admits a firing onto the same permanent job; schedules due together coalesce into one firing, whose TriggeringSchedules names what fired.

Trade-offs

Occurrence history lives in the event ledger rather than in a new job identity, as far as EventRecording keeps it; the job itself stores only its latest successful occurrence's result. Each schedule still needs its own cursor, and coalescing is intentionally not a record of every missed business event.

Run the experiment

Terminal
dotnet run --project learn/100-scheduling/103-multiple-schedules

The twelve-second run lets the five- and ten-second cursors move before printing the proof.

Rows to inspect

Run with --all-columns to execute the visible SELECT * Explore query first. The default Notice queries select the fields that prove the lesson, and the text below explains their meaning.

Expect one jobs_view row, two schedules_view rows, and several events_view executions. The view queries are operator/learning surfaces; code should normally use IJobs and IActaOperations.Schedules.

Break it

Stop the process for more than a minute, restart it, and inspect how the misfire policy advances the cursors (this lab declares none, so the default Skip applies; a cursor less than a minute overdue at a start still fires). Lab 106-schedule-misfire isolates the Skip versus CatchUpOnce decision.

When not to use

Use one-shot jobs when each financial/accounting occurrence needs an independent identity, retention period, deduplication key, or audit outcome. Use an external scheduler when scheduling authority must sit outside the Acta database.

Source trail

The whole program

Every file of learn/100-scheduling/103-multiple-schedules, as it is compiled.

UseLocalDatabase and LearnLab are helpers 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.

multiple-schedules.cs88 lines
multiple-schedules.cs
// How to give one job several schedules
// Several `[Schedule]` attributes on one job share one permanent job, and schedules that come due together fire it
// once.
using Acta;
using Acta.Labs;
using Acta.Learn.MultipleSchedules;
using Microsoft.Extensions.Hosting;

var builder = Host.CreateApplicationBuilder(args);
var lab = new LearnLab(builder.Configuration, args);

builder.Services.UseActa(j =>
{
    j.UseLocalDatabase(builder.Configuration);
    j.Run<MultipleSchedulesJobs>("multiple-schedules");
});

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

Console.WriteLine("Watching two schedule cursors drive one permanent job for 12 seconds...");
await Task.Delay(TimeSpan.FromSeconds(12));

await lab.ShowAllAsync(
    "Explore the complete reusable job record",
    """
    SELECT *
    FROM jobs_view
    WHERE namespace_name = @jobNamespace AND definition_name = @jobName
    """,
    new { jobNamespace = "multiple-schedules", jobName = "report" }
);
await lab.ShowAsync(
    "One permanent job identity, several executions",
    """
    SELECT job_id, job_ref, definition_name, job_status, execution_number
    FROM jobs_view
    WHERE namespace_name = @jobNamespace AND definition_name = @jobName
    """,
    new { jobNamespace = "multiple-schedules", jobName = "report" }
);
await lab.ShowAsync(
    "Two independently moving schedule cursors",
    """
    SELECT schedule_name, schedule_status, expression, next_occurrence_at_utc
    FROM schedules_view
    WHERE namespace_name = @jobNamespace AND definition_name = @jobName
    ORDER BY schedule_name
    """,
    new { jobNamespace = "multiple-schedules", jobName = "report" }
);
await lab.ShowAsync(
    "Occurrence history is append-only events, not new job identities",
    """
    SELECT event, execution_number, created_at_utc
    FROM events_view
    WHERE namespace_name = @jobNamespace AND definition_name = @jobName
    ORDER BY event_id
    """,
    new { jobNamespace = "multiple-schedules", jobName = "report" }
);

await host.StopAsync();

namespace Acta.Learn.MultipleSchedules
{
    public readonly record struct Report;

    public sealed class ReportJob
    {
        [Job("report")]
        // learn: 1. Put several schedules on the one job
        // Several [Schedule]s share one permanent job; schedules due at the same instant coalesce
        // into ONE execution, and context.TriggeringSchedules reports which fired.
        [Schedule("fast", "PT10S")]
        [Schedule("faster", "PT5S")]
        // learn: end
        public Task Handle(Report input, JobContext context, CancellationToken ct)
        {
            // learn: 2. Read which schedules fired this execution
            Console.WriteLine(
                $"{DateTime.UtcNow:HH:mm:ss} UTC fired by [{string.Join(", ", context.TriggeringSchedules.Select(s => s.ScheduleName))}]"
            );
            // learn: end
            return Task.CompletedTask;
        }
    }
}

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.