Job#

class Job(backend: Backend, job_id: str | None = None, **kwargs)[source]#

Abstract handle for a (potentially asynchronous) backend execution.

A Job is returned by Backend.run_async() immediately after submission. The caller can then:

call result() to wait for the outcome and retrieve it, or
poll status / done() / running() / queued() / cancelled() to check the current state, or
call cancel() to attempt cancellation.

This follows the Future (or Promise) pattern: execution happens independently of the caller, and the caller decides when to wait for the outcome.

Design contract

The Job base class defines only the observable contract. That is, the three abstract methods that every concrete job must implement. It deliberately prescribes no internal synchronisation mechanism (no threading, no asyncio, no polling loop). Each concrete subclass chooses whatever concurrency model suits its execution environment:

A synchronous simulator may compute the result inline and make it available before result() is ever called.
An asynchronous hardware backend may submit to a remote queue and poll in a background thread until the result is ready.

From the caller’s perspective, all of the above are used identically.

Parameters:

backendBackend: The backend that created this job.
job_idstr or None: Optional caller-supplied identifier (e.g. a remote job ID assigned by a vendor API). If None, the concrete subclass is responsible for assigning one.
**kwargs: Additional backend-specific metadata to associate with this job. It can be used by any backend implementation as needed.

Properties#

`Job.job_id`	Identifier for this job, or `None` if not yet assigned.
`Job.backend`	The `Backend` that created this job.
`Job.last_known_status`	The most recently cached `JobStatus` for this job.

Abstract Methods#

`Job.result`([timeout])	Block until the job reaches a terminal state and return its result.
`Job.cancel`()	Attempt to cancel the job.
`Job.status`()	Query and return the current `JobStatus` of the job.

Methods#

`Job.__init__`(backend[, job_id])	Initialize a Job instance.
`Job.done`()	Return `True` if the job has completed successfully and results are available.
`Job.running`()	Return `True` if the job is currently executing.
`Job.queued`()	Return `True` if the job is waiting in the backend queue.
`Job.cancelled`()	Return `True` if the job was cancelled.
`Job.in_final_state`()	Return `True` if the job has reached a terminal state.
`Job.refresh`()	Fetch the latest status from the backend and return it.
`Job._raise_for_status`([status])	Raise the appropriate exception if the job did not complete successfully.

Exceptions#

exception JobFailureError[source]#: Raised by Job.result() when the job terminated in ERROR state.

exception JobCancelledError[source]#: Raised by Job.result() when the job was cancelled (CANCELLED).