Generated Code¶

The Background Jobs generator produces standard .NET interfaces for job scheduling and persistence. These work with plain async/await — no effects required.

IJobScheduler¶

Controls job lifecycle — enqueue, schedule, cancel, retry.

// Plain .NET usage (no effects)
public class OrderService(IJobScheduler scheduler)
{
    public async Task<string> EnqueueWelcomeEmail(string userId) =>
        await scheduler.EnqueueAsync(new SendWelcomeEmail(userId));

    public async Task<string> ScheduleInventorySync(string warehouseId) =>
        await scheduler.ScheduleAsync(
            new SyncInventory(warehouseId),
            DateTimeOffset.UtcNow.AddMinutes(30));

    public async Task RetryFailedJob(string jobId) =>
        await scheduler.RetryAsync(jobId);
}

IJobStore¶

Queries persisted job state for monitoring and management.

// Monitor job state
public class JobDashboard(IJobStore store)
{
    public async Task<IReadOnlyList<JobInfo>> GetRunningJobs() =>
        await store.GetJobsAsync(status: JobStatus.Running);

    public async Task<IReadOnlyList<JobInfo>> GetDeadLettered() =>
        await store.GetDeadLetterAsync(limit: 50);
}

JobInfo¶

JobStatus¶

Dispatch Handler Composition¶

The generator composes a dispatch function for each [JobHandler], wiring up retry logic, timeout enforcement, and status tracking. When a job is dequeued, the runtime:

1. Recovers any stalled jobs with expired locks (heartbeat protection)
2. Claims the next available job, ordered by priority
3. Sets a lock expiry (now + TimeoutMs) on the claimed job
4. Starts a heartbeat timer (beats at 1/3 of the timeout interval)
5. Deserializes the payload to the handler's parameter type
6. Invokes the matched [JobHandler] method with timeout enforcement
7. On success, marks the job as completed and re-schedules if it has a cron Schedule
8. On failure, increments AttemptCount and re-enqueues with exponential backoff (RetryDelayMs × 2^attempt)
9. After exhausting retries, moves the job to DeadLettered status
10. On timeout, marks the job as failed with a timeout error message

Heartbeat & Lock Extension¶

While a job is processing, the worker sends periodic heartbeat signals to extend the lock. This prevents other workers from claiming the job while it's still being processed. If a worker crashes without completing a job, the lock expires and RecoverStalledJobsAsync resets it to Pending for another worker to claim.

Lock expires at: now + TimeoutMs
Heartbeat interval: TimeoutMs / 3
Recovery: stalled jobs reset to Pending each poll cycle

Cron Re-Scheduling¶

When a job with a Schedule completes successfully, the worker automatically computes the next occurrence using Cronos and enqueues a new job for that time. The CronSchedulerService also seeds cron jobs at startup to ensure they exist after a fresh deployment.

Event Queue vs Background Jobs¶