Class ShutdownCoordinator

java.lang.Object
express.mvp.myra.transport.lifecycle.ShutdownCoordinator
public final class ShutdownCoordinator extends Object
Coordinates graceful shutdown of transport resources.

This coordinator manages the orderly shutdown of transports, ensuring in-flight operations complete (or timeout) before resources are released. It provides a state machine for shutdown phases and notifies listeners of progress.

Shutdown Flow

1. shutdown() called
   └─▶ Phase: RUNNING → DRAINING
       └─▶ Stop accepting new operations
       └─▶ Wait for in-flight operations (up to drainTimeout)

2. Drain complete OR timeout
   └─▶ Phase: DRAINING → CLOSING
       └─▶ Close all connections
       └─▶ Release backend resources

3. Resources released
   └─▶ Phase: CLOSING → TERMINATED
       └─▶ Notify listeners of completion

Usage Example

ShutdownCoordinator coordinator = new ShutdownCoordinator();

// Track in-flight operations
coordinator.operationStarted();  // When starting a send
coordinator.operationCompleted(); // When send completes

// Initiate graceful shutdown
boolean graceful = coordinator.shutdown(
    Duration.ofSeconds(5),  // Max time to wait for drain
    () -> closeConnections(),
    () -> releaseResources()
);

if (graceful) {
    System.out.println("Shutdown completed gracefully");
} else {
    System.out.println("Forced shutdown due to timeout");
}

Thread Safety

All methods are thread-safe. Phase transitions use atomic operations to ensure correct ordering even with concurrent shutdown requests.

See Also:

  • Constructor Details

    • ShutdownCoordinator

      public ShutdownCoordinator()
      Creates a new shutdown coordinator in RUNNING state.

  • Method Details

    • getPhase

      public ShutdownPhase getPhase()
      Returns the current shutdown phase.
      Returns:
      the current phase

    • isAcceptingOperations

      public boolean isAcceptingOperations()
      Checks if the coordinator is accepting new operations.
      Returns:
      true only if in RUNNING phase

    • isTerminated

      public boolean isTerminated()
      Checks if shutdown has completed.
      Returns:
      true if in TERMINATED phase

    • getInFlightCount

      public int getInFlightCount()
      Returns the number of in-flight operations.
      Returns:
      the count of operations not yet completed

    • addListener

      public void addListener(ShutdownListener listener)
      Registers a listener for shutdown events.

      Listeners can be added at any time. If shutdown has already started, the listener will receive subsequent phase changes but not previous ones.

      Parameters:
      listener - the listener to register

    • removeListener

      public boolean removeListener(ShutdownListener listener)
      Removes a previously registered listener.
      Parameters:
      listener - the listener to remove
      Returns:
      true if the listener was found and removed

    • operationStarted

      public boolean operationStarted()
      Records that an operation has started.

      Call this before starting any tracked operation (send, receive, etc.). Must be paired with operationCompleted().

      Returns:
      true if the operation was accepted, false if shutdown is in progress

    • operationCompleted

      public void operationCompleted()
      Records that an operation has completed.

      Call this when any tracked operation completes (successfully or with error).

    • shutdown

      public boolean shutdown(Duration drainTimeout, Runnable connectionCloser, Runnable resourceReleaser) throws InterruptedException
      Initiates graceful shutdown.

      This method blocks until shutdown is complete or the timeout expires. It progresses through all shutdown phases, calling the provided callbacks at appropriate points.

      Parameters:
      drainTimeout - maximum time to wait for in-flight operations to complete
      connectionCloser - callback to close connections (called in CLOSING phase)
      resourceReleaser - callback to release resources (called before TERMINATED)
      Returns:
      true if shutdown was graceful, false if forced due to timeout
      Throws:
      InterruptedException - if the calling thread is interrupted

    • shutdownNow

      public void shutdownNow(Runnable connectionCloser, Runnable resourceReleaser)
      Initiates immediate (non-graceful) shutdown.

      This skips the drain phase and immediately closes resources.

      Parameters:
      connectionCloser - callback to close connections
      resourceReleaser - callback to release resources

    • awaitTermination

      public boolean awaitTermination(Duration timeout) throws InterruptedException
      Waits for shutdown to complete.
      Parameters:
      timeout - maximum time to wait
      Returns:
      true if terminated within timeout
      Throws:
      InterruptedException - if interrupted while waiting