Class Worker

java.lang.Object
io.superdurable.dex.Worker
All Implemented Interfaces:
AutoCloseable
public final class Worker extends Object implements AutoCloseable
Hosts synchronous Java Step and RPC implementations for registered Flows.

The worker opens outbound pull streams to Dex. It dispatches invocations on a bounded JVM executor. User methods are ordinary blocking Java methods; slow external I/O occupies a handler thread and should respect the configured Step or RPC timeout. Call start() on a dedicated application thread because it blocks until the worker stops. A worker can be started only once. The supplied BlobCache is borrowed and remains the caller's responsibility. 

Worker worker = new Worker(registry, blobCache, WorkerOptions.newBuilder()
        .serverAddress("dex:8801")
        .build());
Runtime.getRuntime().addShutdownHook(new Thread(worker::stop));
worker.start();

  • Constructor Details

    • Worker

      public Worker(Registry registry, BlobCache blobCache)
      Creates a worker using local development defaults.
      Parameters:
      registry - the nonnull registry of Flow implementations
      blobCache - the nonnull cache used to hydrate blob-backed invocation values
      Throws:
      IllegalArgumentException - if either argument is null

    • Worker

      public Worker(Registry registry, BlobCache blobCache, WorkerOptions options)
      Creates a worker with explicit polling, connection, and serialization options.
      Parameters:
      registry - the nonnull registry of Flow implementations
      blobCache - the nonnull cache used to hydrate blob-backed invocation values
      options - the nonnull worker options
      Throws:
      IllegalArgumentException - if any argument is null or the pull Worker ID conflicts with a registered Flow type

  • Method Details

    • start

      public void start()
      Starts the worker pull streams and blocks until termination.

      Only a newly created worker may start. It negotiates the Server protocol before syncing Attribute indexes and opening the pull streams. If the waiting thread is interrupted, the worker stops and restores the thread's interruption status before returning.

      Throws:
      PullRegistrationError - if an uncovered permanent stream rejection stops the Worker with stopOnPermanentStreamRejection enabled, before or after readiness
      IllegalStateException - if the worker was already started or startup fails

    • waitPullRegistered

      public void waitPullRegistered(Duration timeout) throws InterruptedException, TimeoutException
      Waits until every pull queue has received a Registered acknowledgement at least once.

      Start the Worker on another thread. Multiple callers may wait independently, before or after start. Success latches even after stop; use getPullRegistrationState for later probes. Before readiness, a permanent rejection fails this wait only if that queue has no other registered stream. Startup failures are propagated to waiters. Interrupting this wait leaves the Worker running. 

      Thread workerThread = new Thread(worker::start);
workerThread.start();
worker.waitPullRegistered(Duration.ofSeconds(30));
boolean isReady = worker.getPullRegistrationState().isReady();
      Parameters:
      timeout - the nonnull, nonnegative maximum wait duration
      Throws:
      InterruptedException - if the waiting thread is interrupted
      TimeoutException - if the timeout expires before readiness
      PullRegistrationError - if a queue is permanently rejected before readiness
      IllegalArgumentException - if timeout is null or negative
      IllegalStateException - if startup fails or the Worker stops before readiness

    • getPullReservedRpcDeclines

      public long getPullReservedRpcDeclines()
      Returns cumulative Step declines caused by reserved RPC capacity for this Worker.

      The counter counts decline events. Dex may decline the same Step dispatch repeatedly while retrying it, so read the counter as a rate. Full-capacity rejections and unknown names are excluded. The count never resets, remains available after stop, and is safe to read concurrently with handlers. Export this value to a monitoring counter: 

      long declines = worker.getPullReservedRpcDeclines();
      Returns:
      the cumulative reserve-decline count

    • getPullRegistrationState

      public PullRegistrationState getPullRegistrationState()
      Returns an independent snapshot for pull Worker readiness probes.

      After initial readiness, transient failures, reconnects, and stop keep readiness true. A permanent rejection makes it false only while that queue has no registered stream. Re-registration clears the error. Safe concurrently with start, stop, and registration waits. See waitPullRegistered for a startup example.

      Returns:
      immutable queue state

    • stop

      public void stop()
      Gracefully stops the pull streams, handler executor, and server channel.

      The method is idempotent. The Worker drains for the configured stop timeout, then cancels remaining handlers and waits for them to return. A handler ignoring cancellation can block Stop. Interruption status is preserved.

    • close

      public void close()
      Stops the worker and permanently closes its lifecycle.

      The application owns any supplied Credential and the borrowed BlobCache.

      Specified by:
      close in interface AutoCloseable