Class PullWorkerOptions.Builder

java.lang.Object
io.superdurable.dex.PullWorkerOptions.Builder
Enclosing class:
PullWorkerOptions
public static final class PullWorkerOptions.Builder extends Object
Builds immutable outbound polling options.

Obtain a builder from PullWorkerOptions.newBuilder(). Zero values use the defaults documented by each setter. The enclosing type shows a complete Worker example.

  • Method Details

    • maxConcurrentTasks

      public PullWorkerOptions.Builder maxConcurrentTasks(int value)
      Sets the maximum number of concurrent Step and RPC tasks across all queues.

      This also sizes the Worker's handler pool. Assigned tasks above this capacity are rejected so Dex can assign them elsewhere.

      Parameters:
      value - a nonnegative count; zero uses the available CPU count
      Returns:
      this builder
      Throws:
      IllegalArgumentException - if value is negative

    • reservedRpcTasks

      public PullWorkerOptions.Builder reservedRpcTasks(Integer value)
      Reserves handler capacity to protect synchronous RPC latency from long-running Steps.

      Unset reserves one slot when the resolved task limit is at least two, otherwise zero. With the CPU-count default, Steps get one fewer slot than before. Set zero to opt out. With one slot and no explicit reserve, Worker start logs one warning about RPC starvation. Flows must stay responsive because RPCs share Worker task capacity with Steps. WaitFor and Execute tasks, including local attempts, are declined when total busy handlers reach maxConcurrentTasks minus this reserve. RPCs can use the full task limit, including API-direct and transactional RPCs. Declines reassign without consuming an attempt. If all Workers remain at the Step limit until the dispatch wait expires, NO_WORKER_AVAILABLE consumes an attempt and follows the Step retry policy, as when all Workers are full. Local attempts wait the local dispatch wait, then fall back according to their policy. Declines emit a FINE debug log, increment getPullReservedRpcDeclines, and preserve readiness. A queue keeps one extra idle stream for 30 seconds after its last reserve decline. The Worker does not open that stream while all task slots are busy. 

      PullWorkerOptions pull = PullWorkerOptions.newBuilder()
        .maxConcurrentTasks(8).reservedRpcTasks(2).build();
      Parameters:
      value - nonnegative reserved capacity below the resolved limit; null selects the default
      Returns:
      this builder
      Throws:
      IllegalArgumentException - from build if value is negative or reaches the task limit

    • idleStreamsPerQueue

      public PullWorkerOptions.Builder idleStreamsPerQueue(int value)
      Sets the number of waiting streams maintained for each task queue.

      A queue keeps one more stream after a recent reserve decline. Use at least two for Workers with heavy Step backlogs.

      Parameters:
      value - a nonnegative count; zero uses one idle stream per queue
      Returns:
      this builder
      Throws:
      IllegalArgumentException - if value is negative

    • appWorkerID

      public PullWorkerOptions.Builder appWorkerID(String value)
      Sets the process identity used for sticky task routing.

      The ID has 1-63 ASCII letters, digits, periods, underscores, or hyphens. It must differ from every registered Flow type. Empty selects a hostname-derived random ID.

      Parameters:
      value - the Worker ID, or empty to generate one
      Returns:
      this builder
      Throws:
      IllegalArgumentException - if value is null or malformed

    • stopDrainTimeout

      public PullWorkerOptions.Builder stopDrainTimeout(Duration value)
      Sets how long Stop waits for active pull tasks before canceling them.

      A canceled handler must return before Stop completes.

      Parameters:
      value - a nonnegative duration; zero uses 30 seconds
      Returns:
      this builder
      Throws:
      IllegalArgumentException - if value is null or negative

    • stopOnPermanentStreamRejection

      public PullWorkerOptions.Builder stopOnPermanentStreamRejection(boolean value)
      Stops the Worker on a permanent rejection leaving a queue without a registered stream.

      Defaults to false, which retries indefinitely. When enabled, the first such rejection before or after readiness drains within stopDrainTimeout, then makes Worker.start throw PullRegistrationError. Other registered streams for that queue prevent this shutdown. See the enclosing type for a complete options example.

      Parameters:
      value - whether to stop on an uncovered permanent stream rejection
      Returns:
      this builder

    • build

      public PullWorkerOptions build()
      Builds pull options for a Worker.
      Returns:
      immutable pull options