Struct JobHandle 

pub struct JobHandle { /* private fields */ }

A minted, cloneable per-job capability: the public way to observe and await a job you did not run yourself.

Obtain one from Jobs::handle, Jobs::handles, ResidentJobSpawner::spawn, or KeyedJobSpawner::spawn.

The handle is a capability, not a value: it holds no cached state and exposes exactly two operations — load for a point-in-time JobSnapshot, and await_completion for the terminal outcome.

Contracts

1. Live committed reads; no cached state on handles. Every load() is a fresh read.
2. Order preservation: await_all/load_all results[i] ↔ handles[i].
3. Cancel safety: dropping an in-flight await_all/await_completion future (select! loser) leaks nothing and a re-registered wait resolves — the dominant call pattern is tokio::select! against CurrentJob::shutdown_requested.
4. Torn-read-free load(): the entity is authoritative for terminal state — a terminal entity discards any execution row a concurrent completion left visible mid-commit — so load() never reports Pending/Running for a finished job, regardless of isolation level.
5. Honest absence: JobSnapshot::execution_state ⇒ Ok(None) on no-row/no-state; load() ⇒ Err(Find) only if the job never existed.
6. Keyed/resident handle identity: both KeyedJobSpawner::spawn and ResidentJobSpawner::spawn generate the job’s id internally; on the duplicate path the returned handle’s id is the PERSISTED job’s id, not a new one — for keyed, the still-LIVE job holding the key; for resident, the job that exists at all (possibly long-terminal, though a resident job never actually reaches terminal — see crate::ResidentJobCompletion). Either way, callers read the id back from the handle.

Implementations

impl JobHandle

pub fn id(&self) -> JobId

The id of the job this handle observes.

pub async fn load(&self) -> Result<JobSnapshot, JobError>

Load a point-in-time JobSnapshot: runtime status plus the committed execution state, config, and return value.

Errors

Returns JobError::Find if the job never existed.

pub async fn execution_state<S: DeserializeOwned>( &self, ) -> Result<Option<S>, JobError>

Read back only the committed execution state, decoded as S.

A cheap point-read: one single-row SELECT on job_executions, no entity hydration and no snapshot reconciliation — for hot poll loops (e.g. a caught-up barrier) that only need the execution state and would otherwise pay a full load whose cost grows with the event log. Use load() when you need a consistent status/config view.

Honest absence: Ok(None) on a missing row (never spawned, or already terminal) or unset state. Does not distinguish “never existed” from “terminal” — use load if that matters.

Errors

Returns JobError::CouldNotDeserializeExecutionState if the stored state does not decode into S.

pub async fn await_completion( &self, timeout: Duration, ) -> Result<JobOutcome, JobError>

Block until the job reaches a terminal state (completed or errored) and return the outcome together with any result value the runner attached via CurrentJob::set_result.

The timeout is REQUIRED: the await is structurally bounded. Wait-forever is expressed only by an explicit caller loop that re-awaits on JobError::TimedOut — each re-await re-registers a fresh waiter, which is also what makes a lost in-memory notification self-heal instead of wedging.

Errors

Returns JobError::RouterNotStarted if called before Jobs::start_poll. Returns JobError::Find if the job does not exist. Returns JobError::TimedOut if the timeout elapses first. Returns JobError::AwaitCompletionShutdown if the notification channel is dropped (e.g., during shutdown) before delivering the terminal state.

Trait Implementations

impl Clone for JobHandle

fn clone(&self) -> JobHandle

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Extend<JobHandle> for JobHandles

fn extend<I: IntoIterator<Item = JobHandle>>(&mut self, iter: I)

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: T)

🔬This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl FromIterator<JobHandle> for JobHandles

fn from_iter<I: IntoIterator<Item = JobHandle>>(iter: I) -> Self

Creates a value from an iterator.