Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

EDU-3170: Updates Worker Task Queue coverage for Nexus #3284

Merged
merged 6 commits into from
Jan 14, 2025
Merged

EDU-3170: Updates Worker Task Queue coverage for Nexus #3284

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
1485572
EDU-3170: Add Nexus Task Queue coverage to Workers
fairlydurable Jan 8, 2025
61fb0ea
EDU-3170: Updates Worker Task Queue coverage for Nexus
fairlydurable Jan 9, 2025
048b5e7
Merge branch 'main' into EDU-3170
fairlydurable Jan 10, 2025
6ce4771
Update docs/encyclopedia/workers.mdx
fairlydurable Jan 14, 2025
a7980df
Update docs/encyclopedia/workers.mdx
fairlydurable Jan 14, 2025
d295509
Merge branch 'main' of https://github.com/temporalio/documentation in…
fairlydurable Jan 14, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
138 changes: 88 additions & 50 deletions docs/encyclopedia/workers.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,8 +39,7 @@ A Worker Program is the static code that defines the constraints of the Worker P
- [How to run a development Worker using the PHP SDK](/develop/php/core-application#run-a-dev-worker)
- [How to run a development Worker using the Python SDK](/develop/python/core-application#run-a-dev-worker)
- [How to run a development Worker using the TypeScript SDK](/develop/typescript/core-application#run-a-dev-worker)
- [How to run a development Worker using the .NET SDK](/develop/dotnet/core-application#run-worker-process)

- [How to run a development Worker using the .NET SDK](/develop/dotnet/core-application#run-worker-process)<br /><br />
- [How to run a Temporal Cloud Worker using the Go SDK](/develop/go/core-application#run-a-temporal-cloud-worker)
- [How to run a Temporal Cloud Worker using the TypeScript SDK](/develop/typescript/core-application#run-a-temporal-cloud-worker)

Expand Down Expand Up @@ -219,8 +218,7 @@ The Temporal Service interprets the outcome and determines whether to retry the
## What is a Task Queue? {#task-queue}

A Task Queue is a lightweight, dynamically allocated queue that one or more [Worker Entities](#worker-entity) poll for [Tasks](#task).

There are two types of Task Queues, Activity Task Queues and Workflow Task Queues.
There are three types of Task Queues: Activity Task Queues, Workflow Task Queues, and Nexus Task Queues.

<div className="tdiw">
<div className="tditw">
Expand All @@ -235,79 +233,119 @@ There are two types of Task Queues, Activity Task Queues and Workflow Task Queue
</div>
</div>

Task Queues are very lightweight components.
Task Queues do not require explicit registration but instead are created on demand when a Workflow Execution or Activity spawns or when a Worker Process subscribes to it.
When a Task Queue is created, both a Workflow Task Queue and an Activity Task Queue are created under the same name.
There is no limit to the number of Task Queues a Temporal Application can use or a Temporal Service can maintain.
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.

<div className="tdiw">
<div className="tditw">
<p className="tdit">Nexus Endpoint component</p>
</div>
<div className="tdiiw" height="500">
<img
className="img_ev3q"
src="/img/encyclopedia/workers/nexus-task-queue.png"
alt="Task Queue component"
/>
</div>
</div>

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 what we call [Task Routing](#task-routing), which is the routing of specific Tasks to specific Worker Processes or even a specific process.
- 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.
- When all Worker Processes are down, messages simply persist in a Task Queue, waiting for the Worker Processes to recover.
- Task Queues enable [Task Routing](#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 do not need to have any open ports, which is more secure.
- 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 Tasks and Nexus Operations that live on that Queue.
fairlydurable marked this conversation as resolved.
Show resolved Hide resolved

All Workers listening to a given Task Queue must have identical registrations of Activities and/or Workflows.
The one exception is during a Server upgrade, where it is okay to have registration temporarily misaligned while the binary rolls out.
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 four places where the name of the Task Queue can be set by the developer.
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:

- [How to start a Workflow Execution using the Temporal CLI](/cli/workflow#start)
- [How to start a Workflow Execution using the Go SDK](/develop/go/temporal-clients#start-workflow-execution)
- [How to start a Workflow Execution using the Java SDK](/develop/java/temporal-clients#start-workflow-execution)
- [How to start a Workflow Execution using the PHP SDK](/develop/php/temporal-clients#start-workflow-execution)
- [How to start a Workflow Execution using the Python SDK](/develop/python/temporal-clients#start-workflow-execution)
- [How to start a Workflow Execution using the TypeScript SDK](/develop/typescript/temporal-clients#start-workflow-execution)
- [How to start a Workflow Execution using the .NET SDK](/develop/dotnet/temporal-client#start-workflow)
- [How to start a Workflow Execution using the Temporal CLI](/cli/workflow#start)
- [How to start a Workflow Execution using the Go SDK](/develop/go/temporal-clients#start-workflow-execution)
- [How to start a Workflow Execution using the Java SDK](/develop/java/temporal-clients#start-workflow-execution)
- [How to start a Workflow Execution using the PHP SDK](/develop/php/temporal-clients#start-workflow-execution)
- [How to start a Workflow Execution using the Python SDK](/develop/python/temporal-clients#start-workflow-execution)
- [How to start a Workflow Execution using the TypeScript SDK](/develop/typescript/temporal-clients#start-workflow-execution)
- [How to start a Workflow Execution using the .NET SDK](/develop/dotnet/temporal-client#start-workflow)

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

- [How to run a development Worker using the Go SDK](/develop/go/core-application#develop-worker)
- [How to run a development Worker using the Java SDK](/develop/java/core-application#run-a-dev-worker)
- [How to run a development Worker using the PHP SDK](/develop/php/core-application#run-a-dev-worker)
- [How to run a development Worker using the Python SDK](/develop/python/core-application#run-a-dev-worker)
- [How to run a development Worker using the TypeScript SDK](/develop/typescript/core-application#run-a-dev-worker)
- [How to run a development Worker using the .NET SDK](/develop/dotnet/core-application#run-worker-process)

- [How to run a Temporal Cloud Worker using the Go SDK](/develop/go/core-application#run-a-temporal-cloud-worker)
- [How to run a Temporal Cloud Worker using the TypeScript SDK](/develop/typescript/core-application#run-a-temporal-cloud-worker)
- [How to run a development Worker using the Go SDK](/develop/go/core-application#develop-worker)
- [How to run a development Worker using the Java SDK](/develop/java/core-application#run-a-dev-worker)
- [How to run a development Worker using the PHP SDK](/develop/php/core-application#run-a-dev-worker)
- [How to run a development Worker using the Python SDK](/develop/python/core-application#run-a-dev-worker)
- [How to run a development Worker using the TypeScript SDK](/develop/typescript/core-application#run-a-dev-worker)
- [How to run a development Worker using the .NET SDK](/develop/dotnet/core-application#run-worker-process)<br /><br />
- [How to run a Temporal Cloud Worker using the Go SDK](/develop/go/core-application#run-a-temporal-cloud-worker)
- [How to run a Temporal Cloud Worker using the TypeScript SDK](/develop/typescript/core-application#run-a-temporal-cloud-worker)

Note that all Worker Entities listening to the same Task Queue name must be registered to handle the exact same Workflows Types and Activity Types.
Note that all Worker Entities listening to the same Task Queue name must be registered to handle the exact same Workflows Types and Activity Types.
fairlydurable marked this conversation as resolved.
Show resolved Hide resolved

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.
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.
This is optional.
An Activity Execution inherits the Task Queue name from its Workflow Execution if one is not provided.

- [How to start an Activity Execution using the Go SDK](/develop/go/core-application#activity-execution)
- [How to start an Activity Execution using the Java SDK](/develop/java/core-application#activity-execution)
- [How to start an Activity Execution using the PHP SDK](/develop/php/core-application#activity-execution)
- [How to start an Activity Execution using the Python SDK](/develop/python/core-application#activity-execution)
- [How to start an Activity Execution using the TypeScript SDK](/develop/typescript/core-application#activity-execution)
- [How to start an Activity Execution using the .NET SDK](/develop/dotnet/core-application#activity-execution)
- [How to start an Activity Execution using the Go SDK](/develop/go/core-application#activity-execution)
- [How to start an Activity Execution using the Java SDK](/develop/java/core-application#activity-execution)
- [How to start an Activity Execution using the PHP SDK](/develop/php/core-application#activity-execution)
- [How to start an Activity Execution using the Python SDK](/develop/python/core-application#activity-execution)
- [How to start an Activity Execution using the TypeScript SDK](/develop/typescript/core-application#activity-execution)
- [How to start an Activity Execution using the .NET SDK](/develop/dotnet/core-application#activity-execution)

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.
This is optional.
A Child Workflow Execution inherits the Task Queue name from its Parent Workflow Execution if one is not provided.

- [How to start a Child Workflow Execution using the Go SDK](/develop/go/child-workflows)
- [How to start a Child Workflow Execution using the Java SDK](/develop/java/child-workflows)
- [How to start a Child Workflow Execution using the PHP SDK](/develop/php/continue-as-new)
- [How to start a Child Workflow Execution using the Python SDK](/develop/python/child-workflows)
- [How to start a Child Workflow Execution using the TypeScript SDK](/develop/typescript/child-workflows)
- [How to start a Child Workflow Execution using the .NET SDK](/develop/dotnet/child-workflows)

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.

- [How to start a Child Workflow Execution using the Go SDK](/develop/go/child-workflows)
- [How to start a Child Workflow Execution using the Java SDK](/develop/java/child-workflows)
- [How to start a Child Workflow Execution using the PHP SDK](/develop/php/continue-as-new)
- [How to start a Child Workflow Execution using the Python SDK](/develop/python/child-workflows)
- [How to start a Child Workflow Execution using the TypeScript SDK](/develop/typescript/child-workflows)
- [How to start a Child Workflow Execution using the .NET SDK](/develop/dotnet/child-workflows)
- [How to run a Nexus Worker using the Go SDK](https://docs.temporal.io/develop/go/nexus#register-a-nexus-service-in-a-worker)
- [How to run a Nexus Worker using the Java SDK](https://docs.temporal.io/develop/java/nexus#register-a-nexus-service-in-a-worker)

#### Task ordering

Expand Down
Binary file added static/img/encyclopedia/workers/nexus-task-queue.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading