Workers
This guide provides a comprehensive overview of Temporal Workers.
In day-to-day conversations, the term Worker is used to denote either a Worker Program
What is a Worker Program?
A Worker Program is the static code that defines the constraints of the Worker Process, developed using the APIs of a Temporal SDK.
Learn more, a Worker ProcessWhat is a Worker Process?
A Worker Process is responsible for polling a Task Queue, dequeueing a Task, executing your code in response to a Task, and responding to the Temporal Server with the results.
Learn more, or a Worker EntityWhat is a Worker Entity?
A Worker Entity is the individual Worker within a Worker Process that listens to a specific Task Queue.
Learn more.
Temporal documentation aims to be explicit and differentiate between them.
Worker Program
A Worker Program is the static code that defines the constraints of the Worker Process, developed using the APIs of a Temporal SDK.
Implementation guide:
Worker Entity
A Worker Entity is the individual Worker within a Worker Process that listens to a specific Task Queue.
A Worker Entity listens and polls on a single Task Queue. A Worker Entity contains both a Workflow Worker and an Activity Worker so that it may make progress of either a Workflow Execution or an Activity Execution.
Can a Worker handle more Workflow Executions than its cache size or number of supported threads?
Yes it can. However, the trade off is added latency.
Workers are stateless, so any Workflow Execution in a blocked state can be safely removed from a Worker. Later on, it can be resurrected on the same or different Worker when the need arises (in the form of an external event). Therefore, a single Worker can handle millions of open Workflow Executions, assuming it can handle the update rate and that a slightly higher latency is not a concern.
Operation guides:
Worker Process
Component diagram of a Worker Process and the Temporal Server
A Worker Process is responsible for polling a Task QueueWhat is a Task Queue?
A Task Queue is a first-in, first-out queue that a Worker Process polls for Tasks.
Learn more, dequeueing a TaskWhat is a Task?
A Task is the context needed to make progress with a specific Workflow Execution or Activity Execution.
Learn more, executing your code in response to a Task, and responding to the Temporal ClusterWhat is a Temporal Cluster?
A Temporal Cluster is the Temporal Server paired with persistence.
Learn more with the results.
More formally, a Worker Process is any process that implements the Task Queue Protocol and the Task Execution Protocol.
- A Worker Process is a Workflow Worker Process if the process implements the Workflow Task Queue Protocol and executes the Workflow Task Execution Protocol to make progress on a Workflow Execution. A Workflow Worker Process can listen on an arbitrary number of Workflow Task Queues and can execute an arbitrary number of Workflow Tasks.
- A Worker Process is an Activity Worker Process if the process implements the Activity Task Queue Protocol and executes the Activity Task Processing Protocol to make progress on an Activity Execution. An Activity Worker Process can listen on an arbitrary number of Activity Task Queues and can execute an arbitrary number of Activity Tasks.
Worker Processes are external to a Temporal Cluster.
Temporal Application developers are responsible for developing Worker ProgramsWhat is a Worker Program?
A Worker Program is the static code that defines the constraints of the Worker Process, developed using the APIs of a Temporal SDK.
Learn more and operating Worker Processes.
Said another way, the Temporal ClusterWhat is a Temporal Cluster?
A Temporal Cluster is the Temporal Server paired with persistence.
Learn more (including the Temporal Cloud) doesn't execute any of your code (Workflow and Activity Definitions) on Temporal Cluster machines. The Cluster is solely responsible for orchestrating state transitions and providing Tasks to the next available Worker Entity.
While data transferred in Event Histories is secured by mTLS, by default, it is still readable at rest in the Temporal Cluster.
To solve this, Temporal SDKs offer a Data Converter APIWhat is a Data Converter?
A Data Converter is a Temporal SDK component that encodes and decodes data entering and exiting a Temporal Server.
Learn more that you can use to customize the serialization of data going out of and coming back in to a Worker Entity, with the net effect of guaranteeing that the Temporal Cluster cannot read sensitive business data.
In many of our tutorials, we show you how to run both a Temporal Cluster and one Worker on the same machine for local development. However, a production-grade Temporal Application typically has a fleet of Worker Processes, all running on hosts external to the Temporal Cluster. A Temporal Application can have as many Worker Processes as needed.
A Worker Process can be both a Workflow Worker Process and an Activity Worker Process. Many SDKs support the ability to have multiple Worker Entities in a single Worker Process. (Worker entity creation and management differ between SDKs.) A single Worker Entity can listen to only a single Task Queue. But if a Worker Process has multiple Worker Entities, the Worker Process could be listening to multiple Task Queues.
Worker Processes executing Activity Tasks must have access to any resources needed to execute the actions that are defined in Activity Definitions, such as the following:
- Network access for external API calls.
- Credentials for infrastructure provisioning.
- Specialized GPUs for machine learning utilities.
The Temporal Cluster itself has internal workers for system Workflow Executions. However, these internal workers are not visible to the developer.