AsyncJobBackend

class AsyncJobBackend(*args, **kwargs)

Bases: Protocol

Backend that runs circuits as an asynchronous remote job.

Implementations submit work to a scheduler (cloud HPC, hardware queue, etc.) and return an ExecutionResult carrying a job_id rather than circuit results. Callers then poll for status via poll_job_status(), fetch outcomes with get_job_results(), and may cancel_job() an in-flight handle.

Attributes Summary

shots

Number of measurement shots applied to sampling-mode circuits.

Methods Summary

cancel_job(execution_result)	Request cancellation of an in-flight job.
get_job_results(execution_result)	Fetch results for a completed job and return them populated.
poll_job_status(execution_result[, ...])	Query the scheduler-side job state; optionally block until terminal.
submit_circuits(circuits, *[, ...])	Submit a batch of QASM circuits and return a handle.

Attributes Documentation

shots

Number of measurement shots applied to sampling-mode circuits.

Methods Documentation

cancel_job(execution_result)

Request cancellation of an in-flight job.

Must be idempotent: cancelling a job already in a terminal state is a normal race outcome and should not raise (a 409 from the scheduler is acceptable to either swallow or surface as a recognisable exception that callers can ignore).

Return type:

Response

get_job_results(execution_result)

Fetch results for a completed job and return them populated.

Must only be called after poll_job_status() reports a COMPLETED JobStatus.

Return type:

ExecutionResult

poll_job_status(execution_result, loop_until_complete=False, on_complete=None, verbose=True, progress_callback=None, cancellation_event=None)

Query the scheduler-side job state; optionally block until terminal.

Parameters:

• execution_result (ExecutionResult) – Handle returned by submit_circuits().

• loop_until_complete (bool) – If True, poll until a terminal status (COMPLETED / FAILED / CANCELLED); otherwise return after a single query.

• on_complete (Callable[[Response], None] | None) – Invoked with the final HTTP response when a terminal status is reached.

• verbose (bool) – When True, log per-poll status. Disable when rendering progress via progress_callback so user-facing output isn’t doubled.

• progress_callback (Callable[[int, str], None] | None) – Called as (poll_attempt, status_str) for progress-bar updates.

• cancellation_event (Event | None) – When set, the loop exits by raising ExecutionCancelledError. In-flight HTTP requests are not interrupted — cancellation latency is bounded by the per-request timeout.

Returns:

The most recent JobStatus.

submit_circuits(circuits, *, cancellation_event=None, **kwargs)

Submit a batch of QASM circuits and return a handle.

The returned ExecutionResult carries the scheduler-side job_id but no circuit results; populate it via get_job_results() once polling reports a terminal status.

Parameters:

• circuits (Mapping[str, str]) – Mapping of unique label → OpenQASM source.

• cancellation_event (Event | None) – When set, the implementation should refuse to dispatch (or short-circuit dispatch) and raise ExecutionCancelledError. The same event is honoured by poll_job_status() to interrupt an in-flight polling loop.

• **kwargs – Backend-specific options (ham_ops, shot_groups, …).

Return type:

ExecutionResult