Package glide.internal

Class AsyncRegistry

  • public final class AsyncRegistry
extends java.lang.Object
    Async registry for correlating native callbacks with Java CompletableFutures.

    Responsibilities:

    • Maintain a thread-safe mapping from correlation id to the original future
    • Enforce per-client max inflight requests in Java (0 = defer to core default)
    • Schedule optional Java-side timeouts with cancellable tasks
    • Perform atomic cleanup on completion to avoid races and leaks

    Timeouts can be enforced at the Java layer (for immediate user feedback) or deferred to the Rust core (when timeoutMillis = 0). Backpressure defaults and concurrency tuning are handled by the Rust core.

    • Constructor Summary

      Constructors 
      Constructor Description
      AsyncRegistry()  

    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static void cleanupClient​(long clientHandle)
      Clean up per-client tracking when a client is closed.
      static boolean completeCallback​(long correlationId, java.lang.Object result)
      Complete callback with proper race condition handling.
      static boolean completeCallbackWithErrorCode​(long correlationId, int errorTypeCode, java.lang.String errorMessage)
      Complete with error using a structured error code from native layer.
      static void failAllWithError​(java.lang.String errorMessage)
      Fail all pending futures with a ClosingException.
      static int getActiveFutureCount()
      Returns the count of active futures.
      static int getPendingCount()
      Get current pending operation count.
      static int getPendingTimeoutCount()
      Returns the count of pending timeout tasks.
      static boolean isShutdown()
      Returns whether the registry is in shutdown state.
      static <T> long register​(java.util.concurrent.CompletableFuture<T> future, int maxInflightRequests, long clientHandle, long timeoutMillis)
      Register future with client-specific inflight limit, client handle for per-client tracking, and optional Java-side timeout.
      static void removeShutdownHook()
      Remove the automatic shutdown hook, allowing users to manage shutdown manually.
      static void reset()
      Reset all internal state.
      static void shutdown()
      Shutdown cleanup - cancel all pending operations during client shutdown.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Constructor Detail

      • AsyncRegistry

        public AsyncRegistry()

    • Method Detail

      • register

        public static <T> long register​(java.util.concurrent.CompletableFuture<T> future,
                                int maxInflightRequests,
                                long clientHandle,
                                long timeoutMillis)
        Register future with client-specific inflight limit, client handle for per-client tracking, and optional Java-side timeout.

        If the registry is shutting down, the future will be completed exceptionally with a ClosingException and a special correlation ID (0) will be returned to indicate the registration failed.

        Parameters:
        future - the future to register
        maxInflightRequests - per-client limit (0 = no Java-side limit, defer to core)
        clientHandle - native client handle for tracking
        timeoutMillis - Java-side timeout in milliseconds (0 = use Rust default timeout)
        Returns:
        correlation ID for native callback, or 0 if shutdown is in progress

      • completeCallback

        public static boolean completeCallback​(long correlationId,
                                       java.lang.Object result)
        Complete callback with proper race condition handling. Returns false if already completed or timed out.
        Parameters:
        correlationId - the correlation ID from register()
        result - the result to complete with
        Returns:
        true if completed, false if already done

      • completeCallbackWithErrorCode

        public static boolean completeCallbackWithErrorCode​(long correlationId,
                                                    int errorTypeCode,
                                                    java.lang.String errorMessage)
        Complete with error using a structured error code from native layer. Codes map to glide-core RequestErrorType: 0=Unspecified, 1=ExecAbort, 2=Timeout, 3=Disconnect.
        Parameters:
        correlationId - the correlation ID from register()
        errorTypeCode - error type code from native layer
        errorMessage - error message from native layer
        Returns:
        true if completed, false if already done

      • getPendingCount

        public static int getPendingCount()
        Get current pending operation count.

      • shutdown

        public static void shutdown()
        Shutdown cleanup - cancel all pending operations during client shutdown.

      • failAllWithError

        public static void failAllWithError​(java.lang.String errorMessage)
        Fail all pending futures with a ClosingException. Called from the native layer when a fatal infrastructure failure is detected (e.g., callback worker threads terminated or native panic). This ensures no future is left dangling.
        Parameters:
        errorMessage - description of the failure cause

      • cleanupClient

        public static void cleanupClient​(long clientHandle)
        Clean up per-client tracking when a client is closed.

      • reset

        public static void reset()
        Reset all internal state. Intended for test isolation and client shutdown cleanup.

      • getPendingTimeoutCount

        public static int getPendingTimeoutCount()
        Returns the count of pending timeout tasks. Intended for testing to verify timeout tasks are cancelled properly and don't accumulate.
        Returns:
        number of active timeout tasks

      • getActiveFutureCount

        public static int getActiveFutureCount()
        Returns the count of active futures. Intended for testing to verify futures are cleaned up properly.
        Returns:
        number of active futures

      • isShutdown

        public static boolean isShutdown()
        Returns whether the registry is in shutdown state. Intended for testing and diagnostics.
        Returns:
        true if shutdown() or failAllWithError() has been called

      • removeShutdownHook

        public static void removeShutdownHook()
        Remove the automatic shutdown hook, allowing users to manage shutdown manually. Call this if you want to control shutdown behavior yourself.