Skip to content

Status, receipts and filters

Status

Observer.Get returns a dispatch.Status, computed by dispatch.Project from the folded record and a fresh Find. Without a record store it is computed from the Find alone.

Field Type Holds
Job JobID the job's id
Name string JobSpec.Name, a label for people
Level Level job with a store; object-only without one
State State pending, held, running, recovering, succeeded, failed or cancelled
Cause Cause why the job is in that state: the outcome's cause, the hold's, or what the canonical object shows; see classification
Unattended bool a rule the supervisor enforces is in force, the job isn't terminal, and nobody holds the job's ownership; only where the store implements records.Owner
Cleanup CleanupState pending from a cancel until the record settles, then clear; clear for a job never cancelled
Hold *Hold the hold in force, or nil
Submissions []Submission one per submission, in order
History []Event the transitions committed to the record, in order
Plan *Plan the plan as recorded at submit, with each rule's Firings filled in from the record
Supersedes JobID the job this one supersedes; empty for an original job

Status.IdentityWeakened() returns Plan.IdentityWeakened, or "" when there is no plan.

Without a store, Level is object-only, State is running if any object of the job is alive and pending otherwise, and every other field but Job is zero. A job is never reported terminal then, because an object ending is not the job ending.

CleanupState also has the value blocked, which the core doesn't set.

Hold

Field Holds
Kind backend for a hold a person placed with Operator.Hold; recovery for one a hold rule placed after an execution ended
By the actor who placed it
Since, Until when it was placed, and its deadline
Reason why
Overdue true once the deadline has passed; the hold stays, and escalates

Submission

Field Holds
N the submission number, from 1
Canonical the object chosen to run for it, or nil before one is chosen
Executions the canonical object's current execution, as this Find shows it; empty when the object isn't shown
Abandoned a person closed the submission with Abandon

Event

Field Holds
From, To the states before and after
Cause the cause that came with the transition
Submission the submission it concerns
Level job for an event from the record
At when it was committed

The record commits a transition into held, into recovering when a later submission is authorized, and into the terminal state. Running is never one: it comes from the scheduler when you ask. Watch a job's state changes receives these as they happen.

CancelReceipt

Operator.Cancel commits the cancel, then stops every object of the job by name, and reports the two halves apart:

Field Holds
Committed true once the cancel is in the record; from then on it is final
Already the terminal state an earlier outcome left, when the cancel couldn't change it; the zero value, pending, when the job had no outcome
CleanupComplete the stop left nothing of the job alive, and every requeue call the record holds has landed or expired
Live the objects still stopping
CessationUnproven the nodes that objects the stop couldn't prove stopped last ran on, or the object's id when its nodes aren't known; their processes may still be running

When StopJob fails, Cancel returns its error with a receipt whose Committed is true and whose other fields are zero: the cancel stands, and the supervisor's sweeps finish the clean-up.

StopReceipt

Stopper.EmergencyStop stops every object of the job by name without touching the record. Its receipt's one field, Report, is the adapter's StopReport:

Field Holds
Stopped objects verified stopped
Alive objects still alive
Unproven objects whose stop couldn't be verified

Nothing is recorded, so recovery may still happen afterwards.

Filter

Observer.List takes a dispatch.Filter and returns a Status for each job it keeps. It needs a store; without one it returns ErrUnsupported.

Field Default Keeps
States empty: every state jobs whose current State is one of these
Settled false unsettled records only; true adds settled ones

List calls Get for each record, so each job costs a Find on the scheduler. An error from any of them fails the whole list.