1Pause the job
The job is not yet claimable (delayed), so the transition is Applied.
// Enqueue with a 5-second delay so the job sits in a schedulable state and the pause lands before
// the worker can claim it. The delay is resolved on the database clock (db_now + 5s).
var handle = await jobs.ScheduleAsync(new ProcessReport("q3-summary"), TimeSpan.FromSeconds(5));
Console.WriteLine($"Enqueued job {handle.JobRef} with a 5-second delay.");
var pauseResult = await jobs.PauseAsync(handle, "review window");
Console.WriteLine($"PauseAsync -> action={pauseResult.Action} status={pauseResult.Status}");
var resumeResult = await jobs.ResumeAsync(handle, "review complete");
Console.WriteLine($"ResumeAsync -> action={resumeResult.Action} status={resumeResult.Status}");2Resume it
A resume moves the Paused job back to Ready at the due time it kept, so the worker claims it once the 5-second delay is up.
var pauseResult = await jobs.PauseAsync(handle, "review window");
Console.WriteLine($"PauseAsync -> action={pauseResult.Action} status={pauseResult.Status}");
var resumeResult = await jobs.ResumeAsync(handle, "review complete");
Console.WriteLine($"ResumeAsync -> action={resumeResult.Action} status={resumeResult.Status}");3Read the answer: a finished job refuses
A pause of a terminal (Succeeded) job is Rejected, because terminal jobs cannot be paused.
Console.WriteLine($"Job finished with status={status}");
var rejectedResult = await jobs.PauseAsync(handle, "too late");
Console.WriteLine($"PauseAsync on terminal -> action={rejectedResult.Action} blocking-status={rejectedResult.Status}");4Read the reasons on the timeline
Each control leaves an event that carries the reason it was given.
Console.WriteLine($"Job finished with status={status}");
var rejectedResult = await jobs.PauseAsync(handle, "too late");
Console.WriteLine($"PauseAsync on terminal -> action={rejectedResult.Action} blocking-status={rejectedResult.Status}");
var events = await queries.Ledger.ListEventsAsync(new ListEventsQuery(Job: handle));
foreach (var ev in events.Items)
{
if (ev.EventCode is EventCode.JobPaused or EventCode.JobResumed)
Console.WriteLine($" event={ev.EventCode} message={ev.Message ?? "(none)"} details={ev.DetailsText ?? "(none)"}");
}
await host.StopAsync();5The job it acts on
public sealed class ProcessReportJob
{
[Job("process-report")]
public async Task Handle(ProcessReport input, CancellationToken ct)
{
Console.WriteLine($"[{input.Name}] processing started");
await Task.Delay(200, ct);
Console.WriteLine($"[{input.Name}] processing done");
}
}6Run it and check the output
From a clone of the Acta repository, with the .NET 10 SDK:
dotnet run --project learn/300-failure-and-recovery/309-operator-resumePauseAsync -> action=Applied status=Paused
ResumeAsync -> action=Applied status=Ready
Job finished with status=Succeeded
PauseAsync on terminal -> action=Rejected blocking-status=SucceededChecked 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/309-operator-resume, 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.
operator-resume.cs87 lines
// How to pause and resume a job from outside
// `IJobs.PauseAsync` and `ResumeAsync` pause and resume a job from outside its handler. Each answers whether it was
// applied or rejected, and its reason lands on the job's timeline.
using Acta;
using Acta.Learn.OperatorResume;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
var builder = Host.CreateApplicationBuilder(args);
builder.Services.UseActa(j =>
{
j.UseLocalDatabase(builder.Configuration);
j.Run<OperatorResumeJobs>("operator-resume");
});
using var host = builder.Build();
await host.StartAsync();
var jobs = host.Services.GetRequiredService<IJobs>();
var queries = host.Services.GetRequiredService<IActaOperations>();
// Enqueue with a 5-second delay so the job sits in a schedulable state and the pause lands before
// the worker can claim it. The delay is resolved on the database clock (db_now + 5s).
var handle = await jobs.ScheduleAsync(new ProcessReport("q3-summary"), TimeSpan.FromSeconds(5));
Console.WriteLine($"Enqueued job {handle.JobRef} with a 5-second delay.");
// learn: 1. Pause the job
// The job is not yet claimable (delayed), so the transition is Applied.
var pauseResult = await jobs.PauseAsync(handle, "review window");
// learn: end
Console.WriteLine($"PauseAsync -> action={pauseResult.Action} status={pauseResult.Status}");
// learn: 2. Resume it
// A resume moves the Paused job back to Ready at the due time it kept, so the worker claims it once the
// 5-second delay is up.
var resumeResult = await jobs.ResumeAsync(handle, "review complete");
// learn: end
Console.WriteLine($"ResumeAsync -> action={resumeResult.Action} status={resumeResult.Status}");
// Poll until the worker finishes the job (terminal status).
JobStatusCode? status;
do
{
await Task.Delay(300);
status = (await jobs.GetStatusAsync(handle))?.Status;
} while (status is not null && !status.Value.IsFinished);
Console.WriteLine($"Job finished with status={status}");
// learn: 3. Read the answer: a finished job refuses
// A pause of a terminal (Succeeded) job is Rejected, because terminal jobs cannot be paused.
var rejectedResult = await jobs.PauseAsync(handle, "too late");
Console.WriteLine($"PauseAsync on terminal -> action={rejectedResult.Action} blocking-status={rejectedResult.Status}");
// learn: end
// learn: 4. Read the reasons on the timeline
// Each control leaves an event that carries the reason it was given.
var events = await queries.Ledger.ListEventsAsync(new ListEventsQuery(Job: handle));
foreach (var ev in events.Items)
{
if (ev.EventCode is EventCode.JobPaused or EventCode.JobResumed)
Console.WriteLine($" event={ev.EventCode} message={ev.Message ?? "(none)"} details={ev.DetailsText ?? "(none)"}");
}
// learn: end
await host.StopAsync();
namespace Acta.Learn.OperatorResume
{
public sealed record ProcessReport(string Name);
public sealed class ProcessReportJob
{
[Job("process-report")]
public async Task Handle(ProcessReport input, CancellationToken ct)
{
Console.WriteLine($"[{input.Name}] processing started");
await Task.Delay(200, ct);
Console.WriteLine($"[{input.Name}] processing done");
}
}
}