Class AsyncCompletionScope

java.lang.Object
io.fluxzero.sdk.common.AsyncCompletionScope
public final class AsyncCompletionScope extends Object
Thread-local scope for asynchronous work started from completion callbacks.

Completion callbacks sometimes need to start asynchronous side effects, such as aggregate commits, without blocking each callback immediately. This scope lets those callbacks register their futures and waits for all registered work after the callback group has finished running.

The scope is intentionally thread-local. Work registered from other threads is only included when that thread is executing inside the same logical scope.

  • Method Details

    • runAndAwait

      public static void runAndAwait(Runnable task)
      Runs the supplied task inside a new completion scope and waits for all futures registered in that scope.

      If both the task and asynchronous completion fail, the asynchronous failure is added as a suppressed exception to the task failure.

      Parameters:
      task - the task that may register asynchronous completion work

    • runAndAwaitBeforeCommit

      public static void runAndAwaitBeforeCommit(Runnable task)
      Runs a task and awaits its asynchronous work before committing progress.

      Unlike runAndAwait(Runnable), a completion failure takes precedence over a task failure. In particular, a task that intentionally stops partway through a batch must not authorize a partial position commit when asynchronous work for earlier messages has failed. The task failure is retained as a suppressed exception.

      Parameters:
      task - task whose registered asynchronous work must complete successfully before progress is committed

    • register

      public static <T> CompletableFuture<T> register(CompletableFuture<T> future)
      Registers a future with the current completion scope.

      When no scope is active, the future is returned unchanged and no waiting behavior is added. This makes callers free to register futures unconditionally while preserving the normal behavior outside handler or batch completion.

      Type Parameters:
      T - result type of the future
      Parameters:
      future - future to await at the end of the active scope; null is treated as already completed
      Returns:
      the supplied future, or a completed future when future is null

    • register

      public static <T> CompletableFuture<T> register(CompletableFuture<T> future, Runnable afterCompletion)
      Registers a future with the current completion scope and runs a callback after scoped futures have completed.

      The callback runs on the thread that owns the completion scope, after all registered futures have completed and before any asynchronous failure is rethrown from runAndAwait(Runnable). This is useful for cleaning up thread-local state that must remain visible until asynchronous completion work has finished.

      When no scope is active, the future is returned unchanged and the callback is not invoked.

      Type Parameters:
      T - result type of the future
      Parameters:
      future - future to await at the end of the active scope; null is treated as already completed
      afterCompletion - callback to run after scoped futures have completed; may be null
      Returns:
      the supplied future, or a completed future when future is null

    • await

      public static <T> T await(Supplier<CompletableFuture<T>> operation)
      Starts and synchronously awaits an operation whose completion is owned by the caller. Nested transport attempts are not independently added to the surrounding scope: a caller may catch the failure and retry the operation. Other registered side effects remain attached to the batch. Waiting is interruptible; interruption preserves the thread interrupt flag and is reported as a CompletionException.
      Type Parameters:
      T - result type
      Parameters:
      operation - operation whose complete lifecycle is represented by its returned future
      Returns:
      the completed result

    • takeOwnership

      public static <T> CompletableFuture<T> takeOwnership(Supplier<CompletableFuture<T>> operation)
      Starts an operation whose returned future will be awaited or registered by its caller. Only that exact future is removed from automatic batch registration. Other work started by local handlers, interceptors or captured worker contexts remains attached to the enclosing scope.
      Type Parameters:
      T - completion result type
      Parameters:
      operation - operation whose returned completion is owned by the caller
      Returns:
      the operation's future, which the caller must await or register

    • isActive

      public static boolean isActive()
      Returns whether the current thread is executing inside an async completion scope.
      Returns:
      true when futures registered by this thread will be awaited by a surrounding scope

    • captureContext

      public static <T> Supplier<T> captureContext(Supplier<T> supplier)
      Captures the current completion scope and returns a supplier that re-enters it when executed.

      This is intended for framework-managed worker threads that still belong to the same logical handler or batch processing operation. If no scope is active, the original supplier is returned unchanged.

      Type Parameters:
      T - result type
      Parameters:
      supplier - supplier to execute with the captured scope
      Returns:
      a context-aware supplier