Skip to content

The steps Next returns

Step Next asks for it when Fields set The supervisor
StepObserve Find shows an object that's new, or changed in state, cause, hold instance, restart count, admin hold, requeue bit or foreignness Obs commits an observe fact as evidence
StepAuthorize the job has no submission yet; a resubmit rule with budget left covers the cause that ended the canonical execution; a person resubmitted out of a recovery hold; or an abandoned submission needs a successor Submission, TriggerKey, Rule (-1 for none) commits an authorize decision
StepStart the job isn't cancelled, and the latest submission is open with no canonical object and either no attempts yet, or some still unresolved and no more than SubmitRetries made Submission, Attempt commits an attempt decision, calls Backend.Start, then commits the reply as evidence
StepCanonical a submission with no canonical object has unretired objects of its own in Find, ended ones included; the one with the lowest attempt number is chosen Submission, Attempt, Ref commits a canonical decision
StepOpen the canonical object is gated and not admin-held, the job wants to run (or is held with its hold already on the gated object), every duplicate is retired and gone, and every earlier submission's canonical object has been seen ended on a Find taken after its requeue calls expired Submission, Ref commits an opening decision, then calls Backend.Open
StepRetire a live object isn't canonical, and its submission already has a canonical object, was abandoned, or was never authorized; not repeated once retired Ref commits a retire decision
StepStop a retired object is alive; a terminal job has a live object; or the node-loss fence has fallen on the canonical object Ref, Detail calls Backend.Stop, and commits nothing
StepStopJob a cancelled job hasn't been swept yet, or every recorded requeue call has expired since the last sweep none calls Backend.StopJob, then commits a stop-job decision
StepPlaceHold a hold rule covers the cause that ended the canonical execution (Hold set); or a hold an actor placed isn't on the live canonical object yet (Instance set) Submission, Hold, Cause; or Ref, Instance, Op, Deadline, Expires with Hold: commits a hold-placed decision. Otherwise commits a hold-call decision, calls Holder.Hold, and commits hold-refused if it was refused
StepReleaseHold the live canonical object carries a hold instance the record no longer holds, and no release of it is in flight Ref, Instance, Op, Deadline, Expires commits a hold-call decision, then calls Holder.Release
StepRequeue a requeue intent is committed, the canonical object is running, and no restore call on it could still land Ref, Deadline, Expires commits a requeue-call decision, then calls Requeuer.Requeue
StepRestoreRequeue the job has no outcome, Find shows a requeue bit set on a live object of ours, the Find was taken after every recorded requeue and restore call on it landed or expired, and no requeue of it is asked for in the same pass Ref, Deadline, Expires commits a restore-call decision, then calls Requeuer.RestoreRequeueBit
StepCease a recovery hold that a shared checkpoint put in place of a recovery rule stands, the job is held, and the object has never been answered ceased and was last asked at least dispatch.CessationInterval ago Ref calls CessationSignal.Ceased, then commits a cessation fact as evidence; with no CessationSignal, or on an error, the fact says not ceased. A ceased answer lifts the hold, and the rule it stood in for applies again
StepVerifiedStopped a terminal job's recorded object, seen in an earlier Find or returned by a Start reply, is absent from this one Ref, FindAt commits a verified-stopped decision
StepOutcome the canonical execution ended and the plan says the job is finished, or every attempt of a submission was refused Outcome, Cause commits an outcome decision
StepEscalate something needs a person; see escalations Escalation, Detail commits an escalate decision
StepSettle the job is terminal and the settled predicate holds none commits a settled fact, and sets the settled labels
StepWait always, last Wake takes Wake as the time to look again

Next(job, discovery, now) returns steps in the order they are to be carried out, and always ends with one StepWait. A settled job gets no steps at all. Next is pure: it reads only its arguments, so every actor computes the same steps from the same record revision and the same Find.

Decisions and evidence

A decision is committed against the record revision the pass read, carrying the supervisor's ownership lease where the store checks it. If the revision has moved, the commit fails with records.ErrConflict, and the supervisor stops the pass and reads again. If ownership was lost, it fails with records.ErrNotOwner, and Run returns supervise.ErrDisplaced.

Evidence (observe, reply, hold-refused after a refused Hold, cessation, and delivered once an escalation reaches a person) is committed against the pass's revision too, but on a conflict it's re-committed against whatever the revision now is, because a late result is still a fact. The pass then ends and starts again.

Step.Decision() reports whether a step's kind commits a decision. It's true for StepAuthorize, StepCanonical, StepOpen, StepRetire, StepPlaceHold, StepReleaseHold, StepRequeue, StepRestoreRequeue, StepVerifiedStopped, StepOutcome, StepEscalate, StepSettle and StepStopJob.

Calls that carry a deadline

StepPlaceHold (for an actor's hold), StepReleaseHold, StepRequeue and StepRestoreRequeue carry a Deadline, 30 seconds after now (dispatch.CallDeadline), and an Expires, the deadline plus the adapter's CallBound as recorded in the header. Both are committed before the call is sent, so any later reader knows when the call can no longer land. Next doesn't ask to place a new hold instance on an object while any earlier-instance call on it could still land.

A requeue bit is restored only once no requeue call on the object could still land, because a bit seen while one is in flight may be that requeue's own first step. A requeue waits out an in-flight restore for the same reason the other way round: a restore landing between the requeue's first two steps would clear the bit it set, and the requeue would fail with its intent spent. Restore calls don't hold up settlement or the next submission's gate, because a restore landing late can only clear a bit; it can't revive an object.

A supervisor whose adapter has no Holder commits hold-refused instead of calling, and one with no Requeuer does nothing for StepRequeue or StepRestoreRequeue.

When Wait wakes

StepWait.Wake is the earliest future moment something time-based falls due: an active hold's deadline, a recorded call's expiry, a node-loss window ending, an attempt of the latest submission reaching the unresolved age, or the clean-up deadline passing, counted from the cancel or, with no cancel, from the outcome. The age and the deadline are the job's own, 10 and 30 minutes unless WithUnresolvedAge and WithCleanupDeadline set them at submit. It's zero when nothing is due. The supervisor sleeps until then, or its poll interval, or the adapter's watch stream sends something, whichever comes first.