bloqade.core.device.future.Future

← Module overview

classFuture¶source

bloqade.core.device.future.Future

Bases: AuthMixin, Generic[ResultType]

Future for a submitted task.

Signature

class Future(*, context_name: str, qpu_mode: str | None = None, task_id: str, storage: StorageBackend = DictStorage(), fetch_options: ApiFetchOptions = ApiFetchOptions(), result_cls: type[ResultType] = Result)

Public import paths

• from bloqade.core.device import Future
• from bloqade.core.device.task import Future
• from bloqade.core.device.device import Future

A future can poll task status, fetch available shot results into storage, and construct result views over that storage using result_cls.

Parameters

Name	Type	Default	Description
context_name	str	required
qpu_mode	str | None	None
task_id	str	required
storage	StorageBackend	DictStorage()
fetch_options	ApiFetchOptions	ApiFetchOptions()
result_cls	type[ResultType]	Result

Attributes

Name	Type	Description
qpu_mode	str | None	Explicit qlam QPU mode used for backend API calls. When None, qlam-core resolves it from configuration.
task_id	str	Backend task ID.
storage	StorageBackend	Storage backend used for fetched shots and task metadata. Defaults to a fresh `DictStorage` (in-memory; not persisted across processes).
fetch_options	ApiFetchOptions	Pagination and polling options.

methodget_task¶source

bloqade.core.device.future.Future.get_task

def get_task() -> Task

Fetch the current task record from the backend.

Returns

TaskTask: The task object returned by the backend.

source

methodget_compilation¶source

bloqade.core.device.future.Future.get_compilation

def get_compilation(compilation_id: str | None = None)

Fetch the compilation record associated with this task.

Parameters

Name	Type	Default	Description
compilation_id	str | None	None	ID of the compilation to fetch. When `None`, the compilation ID is retrieved from the task record. Defaults to `None`.

Returns

The compilation object returned by the backend.

source

methodfetch¶source

bloqade.core.device.future.Future.fetch

def fetch() -> None

Fetch currently available shot results into this future’s storage.

Results are requested from the first known incomplete subtask page and paginated by both subtask and shot page. Repeated calls are safe because storage backends de-duplicate rows by task ID, shot index, and frame type.

source

methoddone¶source

bloqade.core.device.future.Future.done

def done() -> bool

Return whether the task has reached a terminal status.

Returns

boolbool: `True` if the task status is one of `EXIT_STATUS` (completed, cancelled, failed, or payload processing error).

source

methodstatus¶source

bloqade.core.device.future.Future.status

def status() -> TaskStatus

Return the current status of the task.

Returns

TaskStatusTaskStatus: The task status as reported by the backend.

source

methodcancel¶source

bloqade.core.device.future.Future.cancel

def cancel()

Attempt to cancel the execution of the task.

Returns

The backend cancellation response when cancellation is submitted; otherwise None if cancellation raises and a warning is emitted.

source

methodcancelled¶source

bloqade.core.device.future.Future.cancelled

def cancelled() -> bool

Return whether the task was cancelled.

Returns

boolbool: `True` if the task status is `CANCELLED`.

source

methodresult¶source

bloqade.core.device.future.Future.result

def result(*, timeout: float | None = None) -> ResultType

Wait for completion, fetch results, and return a result view.

Parameters

Name	Type	Default	Description
timeout	float | None	None

Other Parameters

Name	Type	Description
timeout	float | None	Maximum number of seconds to wait for a terminal task status. If None, wait indefinitely. Defaults to None.

Returns

ResultTypeResultType: A result view scoped to this future's task ID and the DETECTED frame type.

Raises

Type	Description
TimeoutError	If `timeout` elapses before a terminal status is reached.
ValueError	If the task was cancelled or failed.

source

methodpartial_result¶source

bloqade.core.device.future.Future.partial_result

def partial_result() -> ResultType

Fetch currently available results and return a result view.

Unlike result, this method does not wait for the task to finish.

Returns

ResultTypeResultType: A result view scoped to this future's task ID and the DETECTED frame type.

source

methodresults_from_storage¶source

bloqade.core.device.future.Future.results_from_storage

Signature

def results_from_storage(shot_filter: ShotFilter | None = None) -> ResultType

Build a result view over this future’s storage.

Parameters

Name	Type	Default	Description
shot_filter	ShotFilter | None	None	Filter to apply to the result view. When None, the view is scoped to this future's task ID and the DETECTED frame type. Defaults to None.

Returns

ResultTypeResultType: A result view over the storage backend.

source

methodexport_to¶source

bloqade.core.device.future.Future.export_to

Signature

def export_to(storage: StorageBackend, chunk_size: int = 1000, shot_filter: ShotFilter | None = None)

Copy stored shots and task definitions to another storage backend.

Parameters

Name	Type	Default	Description
storage	StorageBackend	required	Destination storage backend.
chunk_size	int	1000	Maximum number of shots to write per batch. Defaults to 1000.
shot_filter	ShotFilter | None	None	Optional shot filter. When the filter includes `task_ids`, only those task definitions are copied. Otherwise, all task definitions from this future's storage are copied. Defaults to None.

source

methodfetch_and_export_to¶source

bloqade.core.device.future.Future.fetch_and_export_to

def fetch_and_export_to(storage: StorageBackend, chunk_size: int = 1000)

Fetch available results and export this future’s storage.

Parameters

Name	Type	Default	Description
storage	StorageBackend	required	Destination storage backend.
chunk_size	int	1000	Maximum number of shots to write per batch. Defaults to 1000.

source

methodfrom_storage¶source

bloqade.core.device.future.Future.from_storage

Signature

def from_storage(*, storage: StorageBackend, new_storage: StorageBackend | None = None, task_id: str | None = None, fetch_options: ApiFetchOptions = DEFAULT_FETCH_OPTIONS, context_name: str | None = None, qpu_mode: str | None = None) -> Self

Create a future from task metadata already present in storage.

Parameters

Name	Type	Default	Description
storage	StorageBackend	required	Storage used to discover and validate the task ID.
new_storage	StorageBackend | None	None	Storage backend to attach to the returned future. When None, `storage` is reused. Defaults to None.
task_id	str | None	None	Task ID to attach to. Required when `storage` contains more than one task ID. Defaults to None.
fetch_options	ApiFetchOptions	DEFAULT_FETCH_OPTIONS	Pagination and polling options. Defaults to `ApiFetchOptions()`.
context_name	str | None	None	Name of the qlam context to attach to the returned future. When None, the class-level default on `cls` is used. Defaults to None.
qpu_mode	str | None	None	Explicit qlam QPU mode to attach to the returned future. When None, qlam-core resolves it from configuration. Defaults to None.

Returns

SelfSelf: A future attached to the selected task ID.

Raises

Type	Description
ValueError	If storage has no task IDs, the requested task ID is not present, multiple task IDs are present without an explicit `task_id`, or `context_name` is None and `cls` has no class-level default.

source

methodfrom_task_id¶source

bloqade.core.device.future.Future.from_task_id

Signature

def from_task_id(*, task_id: str, storage: StorageBackend | None = None, fetch_options: ApiFetchOptions = DEFAULT_FETCH_OPTIONS, context_name: str | None = None, qpu_mode: str | None = None) -> Self

Create a future from a backend task ID.

The task record and task definition are fetched from the backend, and the task definition is stored in storage before the future is returned.

Parameters

Name	Type	Default	Description
task_id	str	required	Backend task ID.
storage	StorageBackend | None	None	Storage backend that will receive the task definition and later fetched shots. When None, a fresh `DictStorage` is used (in-memory; not persisted across processes). Defaults to None.
fetch_options	ApiFetchOptions	DEFAULT_FETCH_OPTIONS	Pagination and polling options. Defaults to `ApiFetchOptions()`.
context_name	str | None	None	Name of the qlam context used to fetch the task and attached to the returned future. When None, the class-level default on `cls` is used. Defaults to None.
qpu_mode	str | None	None	Explicit qlam QPU mode used to fetch the task and attached to the returned future. When None, qlam-core resolves it from configuration. Defaults to None.

Returns

SelfSelf: A future attached to `task_id`.

Raises

Type	Description
ValueError	If `context_name` is None and `cls` has no class-level default.

source