Workflow Status

running() observes the handle's loaded state. Call refresh() before observing a workflow that another queue worker is executing. Use a bounded wait with a pause between reads:

$deadline = hrtime(true) + 20_000_000_000;
do {
    $workflow->refresh();
    if (! $workflow->running()) {
        break;
    }
    usleep(100_000);
} while (hrtime(true) < $deadline);

if ($workflow->running()) {
    throw new RuntimeException('Workflow is still running; observation deadline expired.');
}
if (! $workflow->completed()) {
    throw new RuntimeException('Workflow ended with status '.$workflow->status());
}
$result = $workflow->output();

An observation timeout stops this caller's wait. It does not cancel the workflow. Keep the workflow ID so another observer can load its current state. A terminal failure, cancellation or termination must be handled before reading a successful output.

An instance handle from Workflow\V2\WorkflowStub::load($workflowId) follows the current run when refreshed, including across continueAsNew(). A handle from loadRun() or loadSelection() keeps observing the selected run, whose completion can mean it continued into a successor. See Workflow API for run selection and closure details.

Status Values

The status() method returns string statuses:

reserved
pending
running
waiting
cancelled
terminated
completed
failed

• reserved means an instance id has been created but the first start command has not been accepted yet
• pending means the run exists and has work ready to be claimed
• running means a workflow task is actively leased to a worker
• waiting means the run is blocked on a durable resume source such as an activity, timer, or named signal
• cancelled means an accepted engine-level cancel command closed the current run
• terminated means an accepted engine-level terminate command force-closed the current run
• completed, failed, cancelled, and terminated are terminal run states

When a run uses continueAsNew(), the old run ends with status = completed and closed_reason = continued. Waterline keeps that run in the completed bucket while still surfacing the exact closed_reason so operators can see that the instance rolled forward into a newer run.

running() returns true for pending, running, and waiting.

State Machine

This is the state machine for a workflow status.