JobStatus

A Job object contains a lot of metadata on top of the computation results a user wants to get. These can be retrieved from the JobStatus object every job contains.

>>> s = my_job.status  # s is a JobStatus instance
>>> if s.completed:
...    print(f"My job lasted {s.duration} seconds.")
My job lasted 37 seconds.

class perceval.runtime.job_status.JobStatus

Stores metadata related to a job execution

property canceled: bool

Returns:: whether the job is in “CANCELED” status

property completed: bool

Returns:: whether the job has completed, i.e. not waiting or running anymore (corresponding statuses are “SUCCESS”, “ERROR” and “CANCELED”)

property creation_timestamp: float

Returns:: the timestamp the job was created

property duration: float

Returns:: the duration of the job (in seconds)

property failed: bool

Returns:: whether the job has failed to complete (corresponding statuses are “CANCELED” and “ERROR”)

property maybe_completed: bool

Returns:: whether the job has or might have completed (corresponding statuses are “SUCCESS”, “ERROR”, “CANCELED” and “UNKNOWN”)

property progress: float

Returns:: the current job progress (between 0 and 1, 1 meaning 100%)

property running: bool

Returns:: whether the job is running (corresponding statuses are “RUNNING” and “CANCEL_REQUESTED”)

start_run(): Informs that the job is starting. Sets the job start time as the current time and the running status to “RUNNING”

property start_timestamp: float

Returns:: the timestamp the job was started

property status: RunningStatus

Returns:: the job running status

property stop_message: str | None

Returns:: the job stop message, if any. In case of a successful job, this will be None.

stop_run(cause=RunningStatus.SUCCESS, mesg=None)

Informs that the job has just stopped. Sets the job stop time as the current time.

Parameters:

cause (RunningStatus) – running status causing the end of the job
mesg (str | None) – optional additional message related to the end of the job

property success: bool

Returns:: whether the job is in “SUCCESS” status

property unknown: bool

Returns:: whether the job status is unknown

update_progress(progress, phase=None)

Updates the job progress.

Parameters:

progress (float) – the current progress (between 0 and 1, 1 meaning 100%)
phase (str | None) – message related to the current progress

update_times(creation_datetime, start_time, duration)

Set the important times from external information

Parameters:

creation_datetime (float) – the timestamp the job was created
start_time (float) – the timestamp the job was started
duration (float) – the duration of the job (in seconds)

property waiting: bool

Returns:: whether the job is in “WAITING” status

enum perceval.runtime.job_status.RunningStatus(value)

An enumeration.

Valid values are as follows:

WAITING = <RunningStatus.WAITING: 0>: The job is recorded on the Cloud but waits for a computing platform to be available in order to start.

RUNNING = <RunningStatus.RUNNING: 1>: The job is being run on a given computing platform.

SUCCESS = <RunningStatus.SUCCESS: 2>: The job has completed successfully. The full results are to be expected.

ERROR = <RunningStatus.ERROR: 3>: The job has failed and partial results might be available.

CANCELED = <RunningStatus.CANCELED: 4>: The job was canceled either by the user or the system. Partial results might be available.

SUSPENDED = <RunningStatus.SUSPENDED: 5>: The job was halted by the remote system and may be resumed later on.

CANCEL_REQUESTED = <RunningStatus.CANCEL_REQUESTED: 6>: Transitional status leading to CANCELED. The Cloud sent a cancel order to the platform running the job.

UNKNOWN = <RunningStatus.UNKNOWN: 7>: An unknown status code was encountered.

The Enum and its members also have the following methods:

static from_server_response(res)

Converts a job status name from the server to an enum value.

Note

the server name for SUCCESS is “completed”.

Parameters:: res (str) – the job status name
Return type:: RunningStatus
Returns:: the corresponding enum value or UNKNOWN if the status name is unknown.

static to_server_response(status)

Converts a job status enum value to an acceptable name for the server.

Note

SUCCESS is converted to “completed”.

Parameters:: status (RunningStatus) – the job status enum value
Return type:: str
Returns:: the status name