Class WorkerOptions.Builder

java.lang.Object
io.temporal.worker.WorkerOptions.Builder
Enclosing class:
WorkerOptions
public static final class WorkerOptions.Builder extends Object

  • Method Details

    • setMaxWorkerActivitiesPerSecond

      public WorkerOptions.Builder setMaxWorkerActivitiesPerSecond(double maxWorkerActivitiesPerSecond)
      Parameters:
      maxWorkerActivitiesPerSecond - Maximum number of activities started per second by this worker. Default is 0 which means unlimited.
      Returns:
      this

      If worker is not fully loaded while tasks are backing up on the service consider increasing setMaxConcurrentActivityTaskPollers(int).

      Note that this is a per worker limit. Use setMaxTaskQueueActivitiesPerSecond(double) to set per task queue limit across multiple workers.

    • setMaxConcurrentActivityExecutionSize

      public WorkerOptions.Builder setMaxConcurrentActivityExecutionSize(int maxConcurrentActivityExecutionSize)
      Parameters:
      maxConcurrentActivityExecutionSize - Maximum number of activities executed in parallel. Default is 200, which is chosen if set to zero.
      Returns:
      this

      Note setting is mutually exclusive with setWorkerTuner(WorkerTuner)

    • setMaxConcurrentWorkflowTaskExecutionSize

      public WorkerOptions.Builder setMaxConcurrentWorkflowTaskExecutionSize(int maxConcurrentWorkflowTaskExecutionSize)
      Parameters:
      maxConcurrentWorkflowTaskExecutionSize - Maximum number of simultaneously executed workflow tasks. Default is 200, which is chosen if set to zero.
      Returns:
      this

      Note that this is not related to the total number of open workflows which do not need to be loaded in a worker when they are not making state transitions.

      Note setting is mutually exclusive with setWorkerTuner(WorkerTuner)

    • setMaxConcurrentLocalActivityExecutionSize

      public WorkerOptions.Builder setMaxConcurrentLocalActivityExecutionSize(int maxConcurrentLocalActivityExecutionSize)
      Parameters:
      maxConcurrentLocalActivityExecutionSize - Maximum number of local activities executed in parallel. Default is 200, which is chosen if set to zero.
      Returns:
      this

      Note setting is mutually exclusive with setWorkerTuner(WorkerTuner)

    • setMaxConcurrentNexusExecutionSize

      @Experimental public WorkerOptions.Builder setMaxConcurrentNexusExecutionSize(int maxConcurrentNexusExecutionSize)
      Parameters:
      maxConcurrentNexusExecutionSize - Maximum number of nexus tasks executed in parallel. Default is 200, which is chosen if set to zero.
      Returns:
      this

      Note setting is mutually exclusive with setWorkerTuner(WorkerTuner)

    • setMaxTaskQueueActivitiesPerSecond

      public WorkerOptions.Builder setMaxTaskQueueActivitiesPerSecond(double maxTaskQueueActivitiesPerSecond)
      Optional: Sets the rate limiting on number of activities that can be executed per second. This is managed by the server and controls activities per second for the entire task queue across all the workers. Notice that the number is represented in double, so that you can set it to less than 1 if needed. For example, set the number to 0.1 means you want your activity to be executed once every 10 seconds. This can be used to protect down stream services from flooding. The zero value of this uses the default value. Default is unlimited.

      Setting this value to a non-zero value will disable eager execution for activities.

    • setMaxConcurrentWorkflowTaskPollers

      public WorkerOptions.Builder setMaxConcurrentWorkflowTaskPollers(int maxConcurrentWorkflowTaskPollers)
      Sets the maximum number of simultaneous long poll requests to the Temporal Server to retrieve workflow tasks. Changing this value will affect the rate at which the worker is able to consume tasks from a task queue.

      Due to internal logic where pollers alternate between sticky and non-sticky queues, this value cannot be 1 and will be adjusted to 2 if set to that value.

      Default is 5, which is chosen if set to zero.

    • setMaxConcurrentNexusTaskPollers

      @Experimental public WorkerOptions.Builder setMaxConcurrentNexusTaskPollers(int maxConcurrentNexusTaskPollers)
      Sets the maximum number of simultaneous long poll requests to the Temporal Server to retrieve nexus tasks. Changing this value will affect the rate at which the worker is able to consume tasks from a task queue.

      Default is 5, which is chosen if set to zero.

    • setWorkflowPollThreadCount

      @Deprecated public WorkerOptions.Builder setWorkflowPollThreadCount(int workflowPollThreadCount)
      Deprecated.
      Use setMaxConcurrentWorkflowTaskPollers(int)
      Number of simultaneous poll requests on workflow task queue. Note that the majority of the workflow tasks will be using host local task queue due to caching. So try incrementing WorkerFactoryOptions.Builder.setWorkflowHostLocalPollThreadCount(int) before this one.

      Default is 5, which is chosen if set to zero.

    • setMaxConcurrentActivityTaskPollers

      public WorkerOptions.Builder setMaxConcurrentActivityTaskPollers(int maxConcurrentActivityTaskPollers)
      Number of simultaneous poll requests on activity task queue. Consider incrementing if the worker is not throttled due to `MaxActivitiesPerSecond` or `MaxConcurrentActivityExecutionSize` options and still cannot keep up with the request rate.

      Default is 5, which is chosen if set to zero.

    • setActivityPollThreadCount

      @Deprecated public WorkerOptions.Builder setActivityPollThreadCount(int activityPollThreadCount)
      Deprecated.
      Use setMaxConcurrentActivityTaskPollers(int)
      Number of simultaneous poll requests on activity task queue. Consider incrementing if the worker is not throttled due to `MaxActivitiesPerSecond` or `MaxConcurrentActivityExecutionSize` options and still cannot keep up with the request rate.

      Default is 5, which is chosen if set to zero.

    • setLocalActivityWorkerOnly

      public WorkerOptions.Builder setLocalActivityWorkerOnly(boolean localActivityWorkerOnly)
      If set to true worker would only handle workflow tasks and local activities. Non-local activities will not be executed by this worker.

      Default is false.

    • setDefaultDeadlockDetectionTimeout

      public WorkerOptions.Builder setDefaultDeadlockDetectionTimeout(long defaultDeadlockDetectionTimeoutMs)
      Parameters:
      defaultDeadlockDetectionTimeoutMs - time period in ms that will be used to detect workflows deadlock. Default is 1000ms, which is chosen if set to zero.

      Specifies an amount of time in milliseconds that workflow tasks are allowed to execute without interruption. If workflow task runs longer than specified interval without yielding (like calling an Activity), it will fail automatically.

      Returns:
      this
      See Also:

    • setMaxHeartbeatThrottleInterval

      public WorkerOptions.Builder setMaxHeartbeatThrottleInterval(@Nullable Duration interval)
      Parameters:
      interval - the maximum amount of time between sending each pending heartbeat to the server. Regardless of heartbeat timeout, no pending heartbeat will wait longer than this amount of time to send. Default is 60s, which is chosen if set to null or 0.
      Returns:
      this

    • setDefaultHeartbeatThrottleInterval

      public WorkerOptions.Builder setDefaultHeartbeatThrottleInterval(@Nullable Duration interval)
      Parameters:
      interval - the default amount of time between sending each pending heartbeat to the server. This is used if the ActivityOptions do not provide a HeartbeatTimeout. Otherwise, the interval becomes a value a bit smaller than the given HeartbeatTimeout. Default is 30s, which is chosen if set to null or 0.
      Returns:
      this

    • setStickyQueueScheduleToStartTimeout

      public WorkerOptions.Builder setStickyQueueScheduleToStartTimeout(Duration timeout)
      Timeout for a workflow task routed to the "sticky worker" - host that has the workflow instance cached in memory. Once it times out, then it can be picked up by any worker.

      Default value is 5 seconds.

    • setDisableEagerExecution

      public WorkerOptions.Builder setDisableEagerExecution(boolean disableEagerExecution)
      Disable eager activities. If set to true, eager execution will not be requested for activities requested from workflows bound to this Worker.

      Eager activity execution means the server returns requested eager activities directly from the workflow task back to this worker which is faster than non-eager which may be dispatched to a separate worker.

      Defaults to false, meaning that eager activity execution is permitted. Unless you set MaxTaskQueueActivitiesPerSecond, then eager execution is disabled.

    • setUseBuildIdForVersioning

      @Experimental @Deprecated public WorkerOptions.Builder setUseBuildIdForVersioning(boolean useBuildIdForVersioning)
      Deprecated.
      Worker Versioning is now deprecated please migrate to the Worker Deployment API.
      Opts the worker in to the Build-ID-based versioning feature. This ensures that the worker will only receive tasks which it is compatible with.

      Defaults to false

    • setBuildId

      @Experimental @Deprecated public WorkerOptions.Builder setBuildId(String buildId)
      Deprecated.
      Worker Versioning is now deprecated please migrate to the Worker Deployment API.
      Set a unique identifier for this worker. The identifier should be stable with respect to the code the worker uses for workflows, activities, and interceptors.

      A Build Id must be set if setUseBuildIdForVersioning(boolean) is set true.

    • setStickyTaskQueueDrainTimeout

      @Experimental public WorkerOptions.Builder setStickyTaskQueueDrainTimeout(Duration stickyTaskQueueDrainTimeout)
      During graceful shutdown, as when calling WorkerFactory.shutdown(), if the workflow cache is enabled, this timeout controls how long to wait for the sticky task queue to drain before shutting down the worker. If set the worker will stop making new poll requests on the normal task queue, but will continue to poll the sticky task queue until the timeout is reached. This value should always be greater than clients rpc long poll timeout, which can be set via WorkflowServiceStubsOptions.Builder.setRpcLongPollTimeout(Duration).

      Default is not to wait.

    • setWorkerTuner

      public WorkerOptions.Builder setWorkerTuner(WorkerTuner workerTuner)
      Set a WorkerTuner to determine how slots will be allocated for different types of tasks.

    • setUsingVirtualThreads

      @Experimental public WorkerOptions.Builder setUsingVirtualThreads(boolean enable)
      Use Virtual Threads for all the task executors created by this worker. This option is only supported for JDK >= 21. Individual options for different types of workers can be set using the respective methods.

    • setUsingVirtualThreadsOnWorkflowWorker

      @Experimental public WorkerOptions.Builder setUsingVirtualThreadsOnWorkflowWorker(boolean enable)
      Use Virtual Threads for the Workflow task executors created by this worker. This option is only supported for JDK >= 21.

    • setUsingVirtualThreadsOnLocalActivityWorker

      @Experimental public WorkerOptions.Builder setUsingVirtualThreadsOnLocalActivityWorker(boolean enable)
      Use Virtual Threads for the Local Activity task executors created by this worker. This option is only supported for JDK >= 21.

    • setUsingVirtualThreadsOnActivityWorker

      @Experimental public WorkerOptions.Builder setUsingVirtualThreadsOnActivityWorker(boolean enable)
      Use Virtual Threads for the Activity task executors created by this worker. This option is only supported for JDK >= 21.

    • setUsingVirtualThreadsOnNexusWorker

      @Experimental public WorkerOptions.Builder setUsingVirtualThreadsOnNexusWorker(boolean enable)
      Use Virtual Threads for the Nexus task executors created by this worker. This option is only supported for JDK >= 21.

    • setIdentity

      public WorkerOptions.Builder setIdentity(String identity)
      Override identity of the worker primary specified in a WorkflowClient options.

    • setDeploymentOptions

      public WorkerOptions.Builder setDeploymentOptions(WorkerDeploymentOptions deploymentOptions)
      Set deployment options for the worker. Exclusive with setUseBuildIdForVersioning(boolean) and setBuildId(String).

    • setWorkflowTaskPollersBehavior

      public WorkerOptions.Builder setWorkflowTaskPollersBehavior(PollerBehavior pollerBehavior)
      Set the poller behavior for workflow task pollers.

      Note: If the poller behavior is set to PollerBehaviorSimpleMaximum, the maximum number of concurrent workflow task pollers must be at least 2 to account for the sticky and non-sticky task poller. If it is set to 1 it will be automatically adjusted to 2.

      If the sticky queue is enabled, the poller behavior will be used for the sticky queue as well.

    • setActivityTaskPollersBehavior

      public WorkerOptions.Builder setActivityTaskPollersBehavior(PollerBehavior pollerBehavior)
      Set the poller behavior for activity task pollers.

    • setNexusTaskPollersBehavior

      public WorkerOptions.Builder setNexusTaskPollersBehavior(PollerBehavior pollerBehavior)
      Set the poller behavior for nexus task pollers.

    • setAllowActivityHeartbeatDuringShutdown

      @Experimental public WorkerOptions.Builder setAllowActivityHeartbeatDuringShutdown(boolean allowActivityHeartbeatDuringShutdown)
      If true, activities can keep heartbeating during graceful worker shutdown (see WorkerFactory.shutdown). Defaults to false, which means that after graceful shutdown is requested, calling ActivityExecutionContext.heartbeat does not send a heartbeat and instead throws ActivityWorkerShutdownException. This option is ignored by non-graceful shutdown (see WorkerFactory.shutdownNow).

      Note that with this option enabled, activities are no longer notified of the worker shutdown by the ActivityWorkerShutdownException exception, so they are expected to complete within the termination grace period on their own.

    • build

      public WorkerOptions build()

    • validateAndBuildWithDefaults

      public WorkerOptions validateAndBuildWithDefaults()