Acta. Durable execution for .NET

learn actastart jobs

How to choose between starting a job and waiting for it

EnqueueAsync returns as soon as the job is stored; CallAsync enqueues, waits, and returns the job's outcome.

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

Checked every release learn/000-fundamentals/015-call-vs-enqueue
Read as

1Start a job and carry on

EnqueueAsync returns immediately, before the job runs.

call-vs-enqueue.csexcerpt
using var host = builder.Build();
await host.StartAsync();

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

var enqueued = await jobs.EnqueueAsync(new AddNumbers(1, 1));
Console.WriteLine($"EnqueueAsync returned right away: job {enqueued.JobRef}, status {(await enqueued.GetStatusAsync())?.Status}");

var executed = await jobs.CallAsync(CallVsEnqueueJobs.AddNumbers(new AddNumbers(2, 2)));
Console.WriteLine($"CallAsync waited and returned: job {executed.JobId}, result {executed.ValueOrThrow().Sum}");

await host.StopAsync();

2Start a job and wait for its result

CallAsync enqueues, then waits for the job and returns its outcome: ValueOrThrow() gives the result, or throws when the job failed or the wait timed out. It holds its caller that long, and a timeout stops only the wait; inside a handler, call ctx.CallChildAsync instead (213).

call-vs-enqueue.csexcerpt
var jobs = host.Services.GetRequiredService<IJobs>();

var enqueued = await jobs.EnqueueAsync(new AddNumbers(1, 1));
Console.WriteLine($"EnqueueAsync returned right away: job {enqueued.JobRef}, status {(await enqueued.GetStatusAsync())?.Status}");

var executed = await jobs.CallAsync(CallVsEnqueueJobs.AddNumbers(new AddNumbers(2, 2)));
Console.WriteLine($"CallAsync waited and returned: job {executed.JobId}, result {executed.ValueOrThrow().Sum}");

await host.StopAsync();

3The job it acts on

call-vs-enqueue.csexcerpt
public static class AddNumbersJob
{
    [Job("add-numbers")]
    public static async Task<AddNumbersResult> Handle(AddNumbers input, CancellationToken ct)
    {
        await Task.Delay(500, ct);
        return new AddNumbersResult(input.Left + input.Right);
    }
}

4Run it and check the output

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

Terminal
dotnet run --project learn/000-fundamentals/015-call-vs-enqueue
Its output must contain
EnqueueAsync returned right away
CallAsync waited and returned
, result 4

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/000-fundamentals/015-call-vs-enqueue, 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.

call-vs-enqueue.cs54 lines
call-vs-enqueue.cs
// How to choose between starting a job and waiting for it
// `EnqueueAsync` returns as soon as the job is stored; `CallAsync` enqueues, waits, and returns the job's outcome.
using Acta;
using Acta.Learn.CallVsEnqueue;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

var builder = Host.CreateApplicationBuilder(args);

builder.Services.UseActa(j =>
{
    j.UseLocalDatabase(builder.Configuration);
    j.Run<CallVsEnqueueJobs>("call-vs-enqueue");
});

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

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

// learn: 1. Start a job and carry on
// EnqueueAsync returns immediately, before the job runs.
var enqueued = await jobs.EnqueueAsync(new AddNumbers(1, 1));

// learn: end
Console.WriteLine($"EnqueueAsync returned right away: job {enqueued.JobRef}, status {(await enqueued.GetStatusAsync())?.Status}");

// learn: 2. Start a job and wait for its result
// CallAsync enqueues, then waits for the job and returns its outcome: `ValueOrThrow()` gives the result, or throws
// when the job failed or the wait timed out. It holds its caller that long, and a timeout stops only the wait;
// inside a handler, call `ctx.CallChildAsync` instead (213).
var executed = await jobs.CallAsync(CallVsEnqueueJobs.AddNumbers(new AddNumbers(2, 2)));

// learn: end
Console.WriteLine($"CallAsync waited and returned: job {executed.JobId}, result {executed.ValueOrThrow().Sum}");

await host.StopAsync();

namespace Acta.Learn.CallVsEnqueue
{
    public sealed record AddNumbers(int Left, int Right);

    public sealed record AddNumbersResult(int Sum);

    public static class AddNumbersJob
    {
        [Job("add-numbers")]
        public static async Task<AddNumbersResult> Handle(AddNumbers input, CancellationToken ct)
        {
            await Task.Delay(500, ct);
            return new AddNumbersResult(input.Left + input.Right);
        }
    }
}

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.