JobTracker#

Module: iqm.station_control.interface.executor_interface

class JobTracker(*, job_data, _executor, _context=<factory>, _payload=None)#

Bases: ABC, Generic[T_JobDefinition]

Orchestrates the lifecycle of a job, bridging raw data with execution logic.

A JobTracker wraps a static JobData snapshot and uses an ExecutorInterface to perform live actions like status synchronization, waiting for completion, or cancellation.

Attributes

`errors`	All errors formatted as a string.
`job_id`	Unique ID of the job.
`status`	Last queried status of the job.
`job_data`	The underlying job status and metadata.

Methods

`cancel`	Cancel the job.
`find_timeline_entry`	Search the job's execution timeline for an entry matching the specified criteria.
`payload`	Retrieve the original definition/payload used to submit this job.
`update`	Update the job data by querying the execution backend.
`wait_for_completion`	Poll the backend updating the job status, until the job reaches a terminal state, or until we hit a timeout.

Parameters:

job_data (JobData)
_executor (ExecutorInterface)
_context (dict[str, Any])
_payload (T_JobDefinition | None)

job_data: JobData#: The underlying job status and metadata.

property job_id: UUID#: Unique ID of the job.

property status: JobStatus#

Last queried status of the job.

Note that this is not necessarily the same as the current status of the job, unless the status is terminal. To get the current status, use update().

update()#

Update the job data by querying the execution backend.

Modifies job_data. If the job is already in a terminal state (COMPLETED, FAILED, or CANCELLED), no query is performed to save bandwidth.

Returns:: Current status of the job.
Return type:: JobStatus

cancel()#

Cancel the job.

Return type:: None

payload()#

Retrieve the original definition/payload used to submit this job.

If the payload was provided at initialization (e.g., during submission), it is returned immediately. Otherwise, it is fetched from the executor.

Return type:: T_JobDefinition

wait_for_completion(*, timeout_secs=10800.0, polling_interval=1.0, progress_callback=None)#

Poll the backend updating the job status, until the job reaches a terminal state, or until we hit a timeout.

The terminal states are “completed”, “failed”, and “cancelled”.

Will stop the polling (but does not cancel the job) upon receiving a KeyboardInterrupt (Ctrl-C). If you want to cancel the job, call cancel().

Modifies self.

Parameters:

timeout_secs (float) – Maximum time to wait in seconds. If nonzero, the method will return the current status after this period even if it is non-terminal.
polling_interval (float) – Time to wait in seconds between successive status synchronization requests.
progress_callback (Callable | None) – Optional callback function triggered on every status update loop. Receives progress data packets (e.g., queue positions or execution metrics) to update UI progress bars. Defaults to None.

Returns:

Last seen job status.

Raises:

KeyboardInterrupt – Received Ctrl-C while waiting for the job to finish.

Return type:

JobStatus

find_timeline_entry(status, source=None)#

Search the job’s execution timeline for an entry matching the specified criteria.

The timeline is an ordered log of state transitions and events. This method performs a linear search from the beginning of the timeline and returns the first entry that matches the provided status and, optionally, the source.

Parameters:

status (str) – The status string to search for (e.g., “pending”, “running”).
source (Literal['iqm-server', 'iqm-station-control'] | str | None) – The component or service that generated the timeline entry. If provided, only entries from this source are considered. If None (default), entries from any source matching the status will be returned.

Returns:

The first matching TimelineEntry found, or None if no entry in the timeline satisfies the criteria.

Return type:

TimelineEntry | None

property errors: str#: All errors formatted as a string.

Inheritance

JobTracker

Contents

JobTracker#