Skip to main content

Task Queues

This page discusses Task Queues including where to set Task Queues and Task Ordering.

What is a Task Queue?​

A Task Queue is a lightweight, dynamically allocated queue that one or more Worker Entities poll for Tasks. There are three types of Task Queues: Activity Task Queues, Workflow Task Queues, and Nexus Task Queues.

Task Queue component

Task Queue component

A Nexus Endpoint creates an entry point that separates callers from the underlying Nexus Task Queue. The Nexus callers only interact with the Nexus Endpoint. This endpoint routes Nexus Requests to a target Task Queue that's polled by a Nexus Worker.

Nexus Endpoint component

Task Queue component

Task Queues are lightweight components that don’t require explicit registration. They’re created on demand when a Workflow Execution, Activity, or Nexus Operation is invoked, and/or when a Worker Process subscribes to start polling. When a named Task Queue is created, individual Task Queues for Workflows, Activities, and Nexus are created using the same name. A Temporal Application can use, and the Temporal Service can maintain, an unlimited number of Task Queues.

Workers poll for Tasks in Task Queues via synchronous RPC. This implementation offers several benefits:

  • A Worker Process polls for a message only when it has spare capacity, avoiding overloading itself.
  • In effect, Task Queues enable load balancing across many Worker Processes.
  • Task Queues enable Task Routing, which is the routing of specific Tasks to specific Worker Processes or even a specific process.
  • Activity Task Queues support server-side throttling, which enables you to limit the Task dispatching rate to the pool of Worker Processes while still supporting Task dispatching at higher rates when spikes happen.
  • Workflow and Activity Tasks persist in a Task Queue. When a Worker Process goes down, the messages remain until the Worker recovers and can process the Tasks.
  • Nexus and Query Tasks are not persisted. Instead, they are sync matched when, and only when, polled by a Worker. Sync matching immediately matches and delivers a Task to an available Worker without persisting a Task to the Service database. The caller is responsible to retry failed operations. Caller Workflows that invoke Nexus Operations will automatically retry Nexus Tasks until exceeding the Schedule-to-Close timeout.
  • Worker Processes do not need to advertise themselves through DNS or any other network discovery mechanism.
  • Worker Processes connect directly to the Temporal Service for secure communication without needing to open exposed ports.

Any Worker can pick up any Task on a given Task Queue. You must ensure that if a Worker accepts a Task that it can process that task using one of its registered Workflows, Activities, or Nexus Operation handlers. This means that all Workers listening to a Task Queue must register all Workflows, Activities, and Nexus Operations that live on that Queue.

There are two exceptions to this "Task Queue Workers with identical registrations" rule. First, Worker Versioning may be used. During a Worker upgrade binary rollouts, it's okay to have temporarily misaligned registrations. Second, dynamic Workflows or Activity components may be used. If a Task arrives with a recognized method signature, the Worker can use a pre-registered dynamic stand-in.

When Workers don't have a registered Workflow, Activity, Nexus Operation, or dynamic Workflow or Activity component for a given Task, the Task will fail with a "Not Found" error.

  • "Not Found" Workflow Tasks and Activity Tasks are treated as retryable errors.
  • "Not Found" Nexus Operation handlers are non-retryable and must be manually retried from the caller Workflow.

Where to set Task Queues​

There are five places where the name of the Task Queue can be set by the developer.

  1. A Task Queue must be set when spawning a Workflow Execution:

  2. A Task Queue name must be set when creating a Worker Entity and when running a Worker Process:

    Note that all Worker Entities listening to the same Task Queue name must be registered to handle the exact same Workflows Types, Activity Types, and Nexus Operations.

    If a Worker Entity polls a Task for a Workflow Type or Activity Type it does not know about, it will fail that Task. However, the failure of the Task will not cause the associated Workflow Execution to fail.

  3. A Task Queue name can be provided when spawning an Activity Execution:

    This is optional. An Activity Execution inherits the Task Queue name from its Workflow Execution if one is not provided.

  4. A Task Queue name can be provided when spawning a Child Workflow Execution:

    This is optional. A Child Workflow Execution inherits the Task Queue name from its Parent Workflow Execution if one is not provided.

  5. A Task Queue name can be provided when creating a Nexus Endpoint. Nexus Endpoints route requests to the target Task Queue. Nexus Workers poll the target Task Queue to handle the Nexus Tasks, such as starting or cancelling a Nexus Operation.

Task ordering​

Task Queues can be scaled by adding partitions. The default number of partitions is 4.

Task Queues with multiple partitions do not have any ordering guarantees. Once there is a backlog of Tasks that have been written to disk, Tasks that can be dispatched immediately (“sync matches”) are delivered before tasks from the backlog (“async matches”). This approach optimizes throughput.

Task Queues with a single partition are almost always first-in, first-out, with rare edge case exceptions. However, using a single partition limits you to low- and medium-throughput use cases.

note

This section is on the ordering of individual Tasks, and does not apply to the ordering of Workflow Executions, Activity Executions, or Events in a single Workflow Execution. The order of Events in a Workflow Execution is guaranteed to remain constant once they have been written to that Workflow Execution's History.