Skip to main content

Task Queues in PHP

What is a Task Queue?#

From a high level, we can say that a Task Queue is exactly what the name suggests. It is a "first-in-first-out" queue for Tasks, where a Task is the context needed to execute a chunk of code that alters the "state" of a Workflow.

Task Queues are maintained by the Temporal Server. The Server places Tasks into a Task Queue to schedule, start, cancel, and complete parts of a Workflow and/or Activity, for example. A Worker engages in a long poll with a Task Queue, hungrily waiting for a Task to become available. The Worker then executes what ever the Task tells the Worker to do.

How to use Task Queues#

In PHP, a Task Queue is represented in code by name, as a string. There are four places where the name of the Task Queue is supplied by the developer.

  1. When starting a Workflow, a Task Queue name must be provided in the StartWorkflowOptions.
// Create new Workflow Options and set the Task Queue
$workflowOptions = WorkflowOptions::new()
->withTaskQueue("Workflow-Task-Queue-1")
// ...
$yourWorkflow = $workflowClient->newWorkflowStub(
YourWorkflowInterface::class,
$workflowOptions
);
$result = $yourWorkflow->workflowMethod();
  1. A Task Queue name must be provided as a parameter when creating a Worker.
use Temporal\WorkerFactory;
// Create a Worker Factory
$factory = WorkerFactory::create();
// Set the Task Queue when creating the Worker
$worker = $factory->newWorker("Workflow-Task-Queue-1");
// Workflows are stateful. So you need a type to create instances.
$worker->registerWorkflowTypes(YourWorkflow::class);
// start primary loop
$factory->run();

A single Worker can listen to only one Task Queue. And, it is important to remember that the name of the Task Queue the Worker is listening to must match the name of the Task Queue provided in the options to any given Workflow or Activity.

note

All Workers listening to a specific Task Queue must be registered to handle the same Workflows and Activities.

  1. Optionally, the name of a Task Queue can be provided in the ActivityOptions when calling an Activity from a Workflow.
class YourWorkflow implements YourWorkflowInterface
{
private $yourActivity;
public function __construct()
{
// Create Activity options and set the Task Queue
$activityOptions = ActivityOptions::new()
->withTaskQueue("Activity-Task-Queue-1")
// ...
// Create a new Activity Stub and pass the options
$this->yourActivity = Workflow::newActivityStub(
YourActivityInterface::class,
$activityOptions
);
}
public function workflowMethod(): \Generator
{
// Call the Activity
return yield $this->yourActivity->activityMethod();
}
}

If a Task Queue name is not provided in the ActivityOptions, then the Activity Tasks are placed in the same Task Queue as the Workflow Task Queue.

  1. Optionally, the name of a Task Queue can be provided in the ChildWorkflowOptions when calling a Child Workflow.
//Create new Child Workflow Options and set the Task Queue
$childWorkflowOptions = ChildWorkflowOptions::new()
->withTaskQueue("Child-Workflow-Task-Queue-1")
// ...
// Create a new Child Workflow Stub and set the Task Queue
$childWorkflow = Workflow::newChildWorkflowStub(
ChildWorkflowInterface::class,
$childWorkflowOptions
);
// Call the Child Workflow method
$promise = $childWorkflow->workflowMethod();

If a Task Queue name is not provided in the ChildWorkflowOptions, then the Child Workflow Tasks are placed in the same Task Queue as the Parent Workflow Task Queue.

Get notified of updates