Skip to main content

Task Queues in Go

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 Go, 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.
func main() {
// Create the client object
// ...
// Create Workflow options from the client
options := client.StartWorkflowOptions{
TaskQueue: "Workflow-Task-Queue-1",
}
// Prepare Workflow args
// ...
// Then, execute Workflow
we, err := c.ExecuteWorkflow(context.Background(), options, WorkflowFunctionName, args)
if err != nil {
log.Fatalln("unable to complete Workflow", err)
}
// Handle error, result, or store Workflow ID somewhere
// ...
}
  1. A Task Queue name must be provided as a parameter when creating a Worker.
func main() {
// Create the client object
// ...
// Create a Worker, passing it the client, TaskQueue name, and any options
w := worker.New(client, "Workflow-Task-Queue-1", worker.Options{})
w.RegisterWorkflow(WorkflowFunctionName)
// Start listening to the Task Queue
err = w.Run(worker.InterruptCh())
if err != nil {
log.Fatalln("unable to start Worker", err)
}
}

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.
func Workflow(ctx workflow.Context) error {
activityOptions := workflow.ActivityOptions{
TaskQueue: "Activity-Task-Queue-1",
// ...
}
ctx = workflow.WithActivityOptions(ctx, activityOptions)
err := workflow.ExecuteActivity(ctx, ActivityFunctionName).Get(ctx, nil)
if err != nil {
return err
}
return nil
}

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.
func SampleParentWorkflow(ctx workflow.Context) (string, error) {
childWorkflowOptions := workflow.ChildWorkflowOptions{
TaskQueue: "Child-Workflow-Task-Queue-1",
}
ctx = workflow.WithChildOptions(ctx, childWorkflowOptions)
var result string
err := workflow.ExecuteChildWorkflow(ctx, ChildWorkflowFunctionName).Get(ctx, &result)
if err != nil {
return "", err
}
return result, nil
}

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