29. Child jobs as one step holding the outcome
Date: 2026-10-07
Status
Accepted
Context
A handler could not start another job exactly once (outside a step it is scheduled again on every
replay, inside one at least once) or wait for it to end without polling, and jobs had no result.
Waiting through an event published by the child misses children that fail, are cancelled or crash.
The design was discussed in docs/specs/child-jobs.md.
Alternatives considered:
- Separate start and wait steps (
JOB_START+JOB_WAIT): a second name, kind and row per child without new information. - The child’s outcome as an internal event (
job-ended/<id>): events expire after their retention, and failed or crashed children need the same end-of-job hook anyway. - An envelope in
result({"state", "result", "error"}) instead of achild_statecolumn: hides the state from SQL and mixes bikesched’s format with the user’s JSON. - A result returned from the handler (
ResultJobHandler<T>): a second handler type for every registration path; a flag fitscancel()/fail(). - Throwing from
waitForJobon a failed child: control flow by exception. parent_job_idas a foreign key, or a job kind column: deleting a parent would clear the reference, and a kind only repeatsrecurrenceandparent_job_id.- Deadlock detection: event waits don’t declare who publishes, so the wait-for graph is unknown.
Decision
Job.complete(result)sets a job’s result as a flag read after the handler; it is stored inbikesched_jobs.resultonly in the transaction ending the jobSUCCEEDED.Job.newJob(type)returns aStepJobBuilder(noconnection(…), noschedule(Recurrence), nohandler(…): children connect job types registered on their own, inline code is a step) that stores the child (parent_job_id) and aCHILD_JOBstep of the parent in one transaction fenced by the parent’s lock. The step isWAITINGuntil the child ends; every terminal path of a child completes it in the child’s transaction (SUCCEEDEDwithchild_state,result,last_error) and makes a waiting parent due.Job.waitForJob(childId, Class[, Duration])reads that step (only the job’s own children) and returns a sealedJobResult(Succeeded,Failed,Cancelled,CompensationFailed,TimedOut) or suspends the job without a deadline (or until the wait’s stored deadline). A suspension at a child step locks the step row first, so it serializes with the child’s end.- No deadlock detection: job waits form a tree because a job only waits for its own children; cycles through events are bounded by wait timeouts.
- Occurrences of recurring jobs cannot start children, and children cannot be retried with
Bikesched.retry.
Consequences
- Fan-out with exactly-once starts and thread-free waits, and results visible through
findJob. - A child ending while its parent waits elsewhere causes one extra replay of the parent (accepted instead of storing where a job is suspended).
- Terminal writes of child jobs run in a transaction with two extra statements; other jobs are unchanged.
- Parent and child nodes must use compatible
JsonMappers. - Follow-ups: results from
@JobHandlerreturn values and the Spring starter; cancellation propagation to children would need an index onparent_job_id.