Skip to main content

Run a Worker - Ruby SDK

View Markdown

Create and run a Worker​

Create a Temporalio::Worker with a Temporal Client, the Task Queue to poll, and the Workflows and Activities it can execute. Call run to start polling.

features/snippets/worker/worker.rb

worker = Temporalio::Worker.new(
  client: client,
  task_queue: 'my-task-queue',
  workflows: [GreetingWorkflow],
  activities: [SayHello]
)

worker.run

run blocks until the Worker shuts down. To run several Workers in one process, use Temporalio::Worker.run_all, which returns once every Worker it was given has stopped.

Register Workflows and Activities​

All Workers polling the same Task Queue must register the same Workflow Types and Activity Types. A Task Queue does not route by type, so any Worker polling it can receive any Task on that queue. A Worker that receives a Task for a type it did not register fails that Task.

Pass Workflow classes in workflows and Activities in activities. For Activities you can pass either the class or an instance:

worker = Temporalio::Worker.new(
  client:,
  task_queue: 'my-task-queue',
  workflows: [GreetingWorkflow, OrderWorkflow],
  activities: [SayHello, ChargeCard.new(payment_client)]
)

Passing a class makes the Worker instantiate it for each Activity Execution. Passing an instance reuses that object for every execution, which is how Activities share state such as a database client. A shared instance must be thread-safe.

Connect to Temporal Cloud​

To run a Worker against Temporal Cloud, configure the Client connection with your Namespace address and authentication credentials. See Connect to Temporal Cloud for setup instructions.

Configure Worker options​

Temporalio::Worker.new takes keyword arguments that control concurrency limits, pollers, timeouts, and caching, including max_concurrent_activities, max_concurrent_workflow_tasks, and max_cached_workflows. The defaults work for most cases.

To tune these values against real load, see Worker performance and the Worker tuning reference.

Run a versioned Worker​

Set a Worker Deployment Version and enable versioning in deployment_options, then set a versioning behavior on each Workflow.

features/snippets/worker/worker.rb

worker = Temporalio::Worker.new(
  client: client,
  task_queue: 'my-task-queue',
  workflows: [VersionedGreetingWorkflow],
  activities: [SayHello],
  deployment_options: Temporalio::Worker::DeploymentOptions.new(
    version: Temporalio::WorkerDeploymentVersion.new(
      deployment_name: 'my-app',
      build_id: '1.0'
    ),
    use_worker_versioning: true
  )
)

Declare the behavior in the Workflow class with workflow_versioning_behavior Temporalio::VersioningBehavior::PINNED or AUTO_UPGRADE, or set a default for the whole Worker with default_versioning_behavior on DeploymentOptions.

A versioning behavior applies only to a Worker that has versioning enabled. If a Workflow declares one and its Worker does not enable versioning, the server rejects the Workflow Task and the Task retries instead of failing outright.

See Worker Versioning for the available versioning behaviors and how new versions roll out.

Shut down a Worker​

Pass the signals that should stop the Worker to run. The Worker stops polling for new Tasks and waits for in-flight Tasks to finish.

features/snippets/worker/worker.rb

worker.run(shutdown_signals: %w[SIGINT SIGTERM])

You can also pass a block to run, which shuts the Worker down when the block completes, or stop the Worker with a Temporalio::Cancellation. Temporalio::Worker.run_all takes the same shutdown_signals, cancellation, and block, and applies them to every Worker it was given.

See Worker shutdown for what happens to in-flight Workflow Tasks and Activities.