Acta. Durable execution for .NET

learn actawait for people, events, and time

How to read the outcome of a wait that can time out

CallAsync answers a JobOutcome: whether the wait timed out, whether the job failed, and the value when it succeeded.

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

Checked every release learn/300-failure-and-recovery/311-call-outcome-timeout
Read as

1Bound the wait and see whether it timed out

A slow handler with a short WaitTimeout: outcome.TimedOut is true. The job keeps running on the worker; the caller just stops waiting.

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

Console.WriteLine("--- (a) timeout ---");

var opts = new JobExecutionOptions { WaitTimeout = TimeSpan.FromMilliseconds(200), PollInterval = TimeSpan.FromMilliseconds(50) };
var timedOut = await jobs.CallAsync(CallOutcomeTimeoutJobs.SlowReport(), opts);
Console.WriteLine($"TimedOut: {timedOut.TimedOut}");
Console.WriteLine($"Succeeded: {timedOut.Succeeded}");

Console.WriteLine("--- (b) failure ---");

2Read a job that failed

A failing handler: Status is Failed, ThrowIfFailed throws JobFailedException, and TryGetValue is false.

call-outcome-timeout.csexcerpt
Console.WriteLine("--- (b) failure ---");

var failed = await jobs.CallAsync(CallOutcomeTimeoutJobs.FailingReport());
Console.WriteLine($"Status: {failed.Status}");
try
{
    failed.ThrowIfFailed();
}
catch (JobFailedException ex)
{
    Console.WriteLine($"ThrowIfFailed threw: {ex.GetType().Name} job={ex.JobRef} status={ex.TerminalStatus}");
}
Console.WriteLine($"TryGetValue: {failed.TryGetValue(out _)}");

Console.WriteLine("--- (c) success ---");

3Take the value of a job that succeeded

On success, ValueOrThrow returns the handler's result, here the ReportResult("all clear") the job returns.

call-outcome-timeout.csexcerpt
Console.WriteLine("--- (c) success ---");

var success = await jobs.CallAsync(CallOutcomeTimeoutJobs.SuccessReport());
Console.WriteLine($"Succeeded: {success.Succeeded}");
var result = success.ValueOrThrow();
Console.WriteLine($"ValueOrThrow: {result.Summary}");

await host.StopAsync();

4The job it acts on

call-outcome-timeout.csexcerpt
public static class SlowReportJob
{
    [Job("slow-report")]
    public static async Task<ReportResult> Handle(SlowReport input, CancellationToken ct)
    {
        await Task.Delay(TimeSpan.FromSeconds(30), ct);
        return new ReportResult("done");
    }
}

5Run it and check the output

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

Terminal
dotnet run --project learn/300-failure-and-recovery/311-call-outcome-timeout
Its output must contain
TimedOut: True
Status: Failed
ThrowIfFailed threw: JobFailedException
TryGetValue: False
ValueOrThrow: all clear

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/300-failure-and-recovery/311-call-outcome-timeout, 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-outcome-timeout.cs102 lines
call-outcome-timeout.cs
// How to read the outcome of a wait that can time out
// `CallAsync` answers a `JobOutcome`: whether the wait timed out, whether the job failed, and the value when it
// succeeded.
using Acta;
using Acta.Learn.CallOutcomeTimeout;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

var builder = Host.CreateApplicationBuilder(args);

builder.Services.UseActa(j =>
{
    j.UseLocalDatabase(builder.Configuration);
    j.Run<CallOutcomeTimeoutJobs>("call-outcome-timeout");
});

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

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

Console.WriteLine("--- (a) timeout ---");

// learn: 1. Bound the wait and see whether it timed out
// A slow handler with a short WaitTimeout: outcome.TimedOut is true.
// The job keeps running on the worker; the caller just stops waiting.
var opts = new JobExecutionOptions { WaitTimeout = TimeSpan.FromMilliseconds(200), PollInterval = TimeSpan.FromMilliseconds(50) };
var timedOut = await jobs.CallAsync(CallOutcomeTimeoutJobs.SlowReport(), opts);
Console.WriteLine($"TimedOut: {timedOut.TimedOut}");

// learn: end
Console.WriteLine($"Succeeded: {timedOut.Succeeded}");

Console.WriteLine("--- (b) failure ---");

// learn: 2. Read a job that failed
// A failing handler: Status is Failed, ThrowIfFailed throws JobFailedException, and TryGetValue is false.
var failed = await jobs.CallAsync(CallOutcomeTimeoutJobs.FailingReport());
Console.WriteLine($"Status: {failed.Status}");
try
{
    failed.ThrowIfFailed();
}
catch (JobFailedException ex)
{
    Console.WriteLine($"ThrowIfFailed threw: {ex.GetType().Name} job={ex.JobRef} status={ex.TerminalStatus}");
}
Console.WriteLine($"TryGetValue: {failed.TryGetValue(out _)}");

// learn: end

Console.WriteLine("--- (c) success ---");

// learn: 3. Take the value of a job that succeeded
// On success, ValueOrThrow returns the handler's result, here the `ReportResult("all clear")` the job returns.
var success = await jobs.CallAsync(CallOutcomeTimeoutJobs.SuccessReport());
Console.WriteLine($"Succeeded: {success.Succeeded}");
var result = success.ValueOrThrow();

// learn: end
Console.WriteLine($"ValueOrThrow: {result.Summary}");

await host.StopAsync();

namespace Acta.Learn.CallOutcomeTimeout
{
    public readonly record struct SlowReport;

    public readonly record struct FailingReport;

    public readonly record struct SuccessReport;

    public sealed record ReportResult(string Summary);

    public static class SlowReportJob
    {
        [Job("slow-report")]
        public static async Task<ReportResult> Handle(SlowReport input, CancellationToken ct)
        {
            await Task.Delay(TimeSpan.FromSeconds(30), ct);
            return new ReportResult("done");
        }
    }

    public static class FailingReportJob
    {
        [Job("failing-report", MaxAttempts = 1)]
        public static Task<ReportResult> Handle(FailingReport input)
        {
            throw new InvalidOperationException("report source unavailable");
        }
    }

    public static class SuccessReportJob
    {
        [Job("success-report")]
        public static Task<ReportResult> Handle(SuccessReport input)
        {
            return Task.FromResult(new ReportResult("all clear"));
        }
    }
}

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.