Background jobs

Applies to: Rubian builds that include bg, jobs and job_result

Updated September 16, 2026

Background jobs let you start Ruby work and return to the prompt while it runs. This reference applies to builds with bg, jobs and job_result. Job identifiers belong to the Rubian session; they are not interchangeable with machine process identifiers.

Start and inspect a job#

id = bg(name: 'sum-example', timeout: 10) { (1..100).sum }
bg(id)
answer = job_result(id, wait: true, timeout: 2)
puts answer

The job returns 5050. bg prints a start message and returns the identifier. bg(id) displays a summary and returns the job record. A fast operation may already be complete by the time you inspect it.

Commands and arguments#

Command	Purpose and return value
`bg(work = nil, name: nil, timeout: nil) { ... }`	Starts a block, callable or string of Ruby code; returns a job ID. `timeout` is an optional positive number of seconds.
`bg(id)`	Displays and returns one job record, or `nil` if the ID is unknown.
`bg(:list)`	Displays jobs and returns their IDs.
`jobs(filter = nil, quiet: false)`	Returns job records. An optional filter matches job names or submitted code, without case sensitivity. `quiet: true` suppresses the listing.
`job_result(id, wait: false, timeout: nil)`	Returns the retained result. With `wait: true`, waits for completion, optionally up to the specified number of seconds.
`kill_job(id)`	Requests cancellation of an active job. Returns `true` when cancellation was requested and `false` when no cancellable job was found.
`prune_jobs`	Removes terminal job records and returns the removed IDs.

The time limit on bg limits the job. The time limit on job_result limits how long the caller waits. A wait that ends does not itself cancel the job.

Read the state before interpreting a result#

State	Interpretation
`queued`	The job has been accepted and has not yet entered running state.
`running`	The work has started and has no terminal result yet.
`completed`	The work returned normally. Its return value can legitimately be `nil`.
`failed`	The work raised an error. Inspect the record's `error` value.
`cancelled`	Cancellation ended the job.
`timed_out`	The job ended after its configured execution limit.

job_result returning nil does not distinguish an unknown job, unfinished work, an error or a successful nil result. Inspect the job record when that distinction matters.

record = bg(id)
puts record[:error] if record && record[:error]

Cancel and clean up#

Use kill_job(id) for the specific work you intend to stop, then inspect the record again. Cancellation does not reverse earlier file writes or external actions. Keep the job record until you have examined its result and any error; prune_jobs removes the terminal records for the session.

A background job is not a restart-persistent service. For work that should be restored in a provisioned environment, see Recurring work. For separately managed application services, use the Kestowv pilot manual.