Jobs and status¶

Meshing and simulation methods return typed jobs because both operations can queue and allocate managed compute.

Job status¶

class gradientdynamics.jobs.JobStatus¶

Lifecycle state of an asynchronous operation.

QUEUED = queued¶: Accepted and waiting for capacity.

RUNNING = running¶: Active preparation, meshing, solution or export work.

COMPLETED = completed¶: Result and manifest committed successfully.

FAILED = failed¶: Terminal execution failure. Inspect Job.error.

CANCELLED = cancelled¶: Stopped before completion by the client or platform.

Generic job¶

class gradientdynamics.jobs.Job[T]¶

Handle to one asynchronous operation whose successful result is type T.

id: str¶: Opaque job identifier.

status: JobStatus¶

progress: float | None¶: Best available completion estimate from 0.0 to 1.0.

stage: str | None¶: Diagnostic stage label. Treat status as the lifecycle contract.

error: JobError | None¶: Structured terminal error, available when status is FAILED.

refresh() → Job[T]¶: Read current state from the service and return the updated job.

wait(*, timeout: float | None = None, poll_interval: float = 5.0) → Job[T]¶: Poll until the job reaches a terminal state. Raises TimeoutError if the local timeout expires without cancelling remote work.

cancel() → Job[T]¶: Request cancellation and return the refreshed job state.

result() → T¶: Return the completed typed result. Raises gradientdynamics.exceptions.ResourceNotReadyError before completion or gradientdynamics.exceptions.JobFailedError after failure.

Waiting and monitoring¶

from gradientdynamics.jobs import JobStatus

job = geometry.mesh(mesh_config, idempotency_key="baseline-mesh-v1")

while job.refresh().status not in {
    JobStatus.COMPLETED,
    JobStatus.FAILED,
    JobStatus.CANCELLED,
}:
    print(job.stage, job.progress)

mesh = job.result()

For most scripts, the compact form is sufficient:

mesh = geometry.mesh(mesh_config).wait(timeout=3600).result()

Idempotency and retries¶

Supply a stable idempotency key when a lost network response could otherwise create duplicate work. A network interruption does not imply job failure; retrieve or refresh the original job before submitting a replacement.

Clients should respect server-provided retry delays, use bounded backoff and avoid concurrent poll loops for the same job. Approved integrations can also receive authenticated progress callbacks; the job object remains the authoritative record.