GizStack
View .mdOpen in ChatGPTOpen in Claude

gizapp/jobs

Durable jobs on GizDB: one record for a one-off job, a recurring one and a long run with checkpoints. A claim takes the next generation of the job's lease (Task.claimLease), and a worker writes only while the lease of its generation holds; every change is a compare-and-set on the job's id, generation and state, so a stale claim never settles a job. Delivery can repeat (a lost lease, a retry), so a handler uses the job's id to stay idempotent. A failure that finish settles is retried after 1 s, then 2 s: MAX_ATTEMPTS runs in all. A run that advance steps decides its own retries (a checkpoint), so an error it throws ends it.

gizlang
import * as Jobs from "gizapp/jobs";

Types

Job

gizlang
type Job = { @Model.Key id: string; @Model.Min(0) owner: string; operation: string; @Model.Min(0) input: string; @Model.Values("queued,running,waiting,paused,cancelled,failed,done") state: string; @Model.Min(0) checkpoint: string; @Model.Min(0) output: string; @Model.Min(0) error: string; attempts: i64; due: i64; @Model.Column("interval_ms") intervalMs: i64; revision: i64; lease: i64; elapsed: i64; @Model.Column("max_ms") maxMs: i64; created: i64; }

One job. owner is who it is for (a project; empty: the app). due is when it may run and lease when the running claim of generation revision ends (ms). A recurring job has intervalMs; a run with a budget has maxMs of elapsed time. checkpoint is where a run that yields goes on; output is what a finished job gives.

  • id: string
  • owner: string
  • operation: string
  • input: string
  • state: string
  • checkpoint: string
  • output: string
  • error: string
  • attempts: i64
  • due: i64
  • intervalMs: i64
  • revision: i64
  • lease: i64
  • elapsed: i64
  • maxMs: i64
  • created: i64

Finish

gizlang
type Finish = (scoped: Data.Db) => bool throws Model.Rejection

What a run ends with, in the transaction that settles it.

Step

gizlang
type Step = | { kind: "checkpoint"; value: string; afterMs: Option<i64>; } | { kind: "waiting"; value: string; } | { kind: "complete"; output: string; finish: Option<Finish>; } | { kind: "failed"; error: string; finish: Finish; } | { kind: "cancelled"; finish: Finish; }

What one attempt of a run did: yield at a checkpoint (due again after afterMs, or now), wait for a person, or end.

  • checkpoint
  • waiting
  • complete
  • failed
  • cancelled

Execute

gizlang
type Execute = (job: Job) => Step throws string

One attempt of the claimed job. A thrown error is retried as a failure of finish is.

Functions

install

gizlang
function install(d: Data.Db): bool throws Model.Rejection

Makes the jobs table when it is not there.

Effects: fail, read, write, console, io, alloc.

job

gizlang
function job(id: string, owner: string, operation: string, input: string, maxMs: i64, now: i64): Job throws string

A job ID of OPERATION with INPUT for OWNER, with MAX_MS of run time (0: no budget), made and due at NOW.

Effects: fail.

enqueue

gizlang
function enqueue(d: Data.Db, id: string, operation: string, input: string, due: i64): bool throws Model.Rejection

Queues a job of OPERATION with INPUT under the fresh ID, due at DUE.

Effects: fail, read, write, console, io, alloc.

schedule

gizlang
function schedule(d: Data.Db, name: string, operation: string, interval: i64, due: i64): bool throws Model.Rejection

Runs OPERATION every INTERVAL ms under the job id "schedule:NAME", first at DUE. A second call changes its operation and interval and keeps its state.

Effects: fail, read, write, console, io, alloc.

wait

gizlang
function wait(d: Data.Db, id: string, ms: i64): Option<Job> throws Model.Rejection

The job ID once it is no longer queued, running or waiting, or as it is after MS; none when there is no such job. It only reads: the workers of serve or advance run the job.

Effects: fail, read, write, console, io, alloc.

next

gizlang
function next(d: Data.Db): Option<i64> throws Model.Rejection

When the next job is due or its lease ends, so a worker sleeps until then; none when no job waits.

Effects: fail, read, write, console, io, alloc.

claim

gizlang
function claim(d: Data.Db, now: i64, leaseMs: i64 = LEASE_MS): Option<Job> throws Model.Rejection

Claims the job that is due first at NOW, if any, for LEASE_MS.

Effects: fail, read, write, console, io, alloc.

take

gizlang
function take(d: Data.Db, job: Job, now: i64, leaseMs: i64 = LEASE_MS): Option<Job> throws Model.Rejection

Claims JOB at NOW for LEASE_MS when it is due, or running under a lease that ended: its next generation. None when it is not claimable or another worker claimed it first. A running job whose attempts are spent ends here instead.

Effects: fail, read, write, console, io, alloc.

ended

gizlang
function ended(job: Job, error: string, now: i64): Job

JOB after it ran at NOW: done, or, with an ERROR, due again until its attempts are spent. A recurring job is due again one interval after its last due time.

Effects: fail, alloc.

finish

gizlang
function finish(d: Data.Db, job: Job, error: string, now: i64): bool throws Model.Rejection

Settles the claim JOB at NOW, as ended says. False when JOB is no longer the current claim or its lease ended.

Effects: fail, read, write, console, io, alloc.

control

gizlang
function control(context: Table.Context, job: Job, state: string): bool throws string

Moves JOB to STATE on the word of CONTEXT's person, as the Gate admits: pause or cancel it, queue a paused or waiting one again, or "retry" an ended one from its input alone. Each starts a new generation, so the worker of the old one can no longer write.

Effects: fail, read, write, console, io, alloc.

fence

gizlang
function fence(held: Data.Db, job: Job, now: i64): void throws Model.Rejection

Refuses the transaction HELD unless JOB is still the current claim at NOW, so a write in it is the worker's own.

Effects: fail, read, write, console, io, alloc.

fenced

gizlang
function fenced(context: Table.Context, job: Job, work: (scoped: Data.Db) => bool throws Model.Rejection): bool throws Model.Rejection

A Desk write in the transaction of WORK is admitted only for the current generation of JOB.

Effects: fail, read, write, console, io, alloc.

advance

gizlang
function advance(context: Table.Context, before: Job, execute: Execute, leaseMs: i64 = LEASE_MS): bool throws string

One attempt of the job BEFORE: claims it, runs EXECUTE within its budget while a heartbeat renews the lease, and settles it with the step's own writes in one transaction. False when another worker holds it or took it first.

Effects: fail, read, write, console, io, alloc.

serve

gizlang
function serve(db: Data.Db, context: () => Table.Context, execute: Execute, concurrency: i64 = 4, operations: Vec<string> = []): void

Runs every queued job of DB (of OPERATIONS only, when given), and every running one whose worker's lease ran out, for as long as the host runs; each attempt gets a fresh CONTEXT.

Effects: fail, read, write, console, io, alloc.

current

gizlang
function current(job: Job): Query.Query<Job>

The stored record of JOB: the same id, generation and state. A claim's worker is current while it finds one.

Effects: fail, read, write, console, io, alloc.

Constants

MAX_ATTEMPTS

gizlang
const MAX_ATTEMPTS: i64 = 3

The runs a job gets before it fails for good.

LEASE_MS

gizlang
const LEASE_MS: i64 = 30000

How long a claim holds a job before another worker may take it; advance renews it while its work runs.