Package: org.apache.groovy.runtime.async

## [Java] Class GroovyPromise<T>

- org.apache.groovy.runtime.async.GroovyPromise

- All Implemented Interfaces and Traits:
    Awaitable

      public class GroovyPromise<T>
      extends Object
      implements Awaitable

  Default Awaitable implementation backed by a CompletableFuture.

  This is the concrete type returned by `async` methods. It delegates all operations to an underlying `CompletableFuture` while keeping the public API limited to the `Awaitable` contract, thereby decoupling user code from JDK-specific async APIs.

  This class is an internal implementation detail and should not be referenced directly by user code. Use the Awaitable interface instead.

  Type Parameters:
    `T` - the result type
  See Also:
    Awaitable
  Since:
    6.0.0

- - ### Constructor Summary

    Constructors
    Constructor and description
    `GroovyPromise(CompletableFuture<T> future)` Creates a new `GroovyPromise` wrapping the given CompletableFuture.

  - ### Methods Summary

    Methods
    Type Params | Return Type | Name and description
    --- | --- | ---
    `` | `public boolean` | `cancel()` Attempts to cancel this computation.
    `` | `public Awaitable<T>` | `exceptionally(Function<Throwable, ? extends T> fn)` Returns a new `Awaitable` that, if this one completes exceptionally, applies the given function to the exception to produce a recovery value. The throwable passed to the function is deeply unwrapped to strip JDK wrapper layers. Parameters: `fn` - the recovery function Returns: a new awaitable that recovers from failures
    `` | `public T` | `get()` Blocks until the computation completes and returns the result. throws: InterruptedException if the calling thread is interrupted while waiting throws: ExecutionException if the computation completed exceptionally Returns: the computed result
    `` | `public T` | `get(long timeout, TimeUnit unit)` Blocks until the computation completes or the timeout expires. throws: InterruptedException if the calling thread is interrupted while waiting throws: ExecutionException if the computation completed exceptionally throws: TimeoutException if the wait timed out Parameters: `timeout` - the maximum time to wait `unit` - the time unit of the timeout argument Returns: the computed result
    `` | `public boolean` | `isCancelled()` Returns `true` if the computation was cancelled before completing normally. Returns: `true` if cancelled
    `` | `public boolean` | `isCompletedExceptionally()` Returns `true` if this computation completed exceptionally (including cancellation). Returns: `true` if completed with an error or cancellation
    `` | `public boolean` | `isDone()` Returns `true` if the computation has completed (normally, exceptionally, or via cancellation). Returns: `true` if complete
    `<T>` | `public static GroovyPromise<T>` | `of(CompletableFuture<T> future)` Creates a `GroovyPromise` wrapping the given CompletableFuture.
    `<U>` | `public Awaitable<U>` | `then(Function<? super T, ? extends U> fn)` Returns a new `Awaitable` whose result is obtained by applying the given function to this awaitable's result when it completes. Parameters: `fn` - the mapping function Type Parameters: `U` - the type of the mapped result Returns: a new awaitable holding the mapped result
    `<U>` | `public Awaitable<U>` | `thenCompose(Function<? super T, ? extends Awaitable<U>> fn)` Returns a new `Awaitable` produced by applying the given async function to this awaitable's result, flattening the nested `Awaitable`. This is the monadic `flatMap` operation for awaitables. Parameters: `fn` - the async mapping function that returns an `Awaitable` Type Parameters: `U` - the type of the inner awaitable's result Returns: a new awaitable holding the inner result
    `` | `public CompletableFuture<T>` | `toCompletableFuture()` Converts this `Awaitable` to a JDK CompletableFuture for interoperability with APIs that require it. Returns: a `CompletableFuture` representing this computation
    `` | `public String` | `toString()` Returns a human-readable representation showing the promise state: `GroovyPromise{pending`}, `GroovyPromise{completed`}, or `GroovyPromise{failed`}.

  - ### Inherited Methods Summary

    Inherited Methods
    Methods inherited from class | Name
    --- | ---
    `class Object` | `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### public GroovyPromise(CompletableFuture<T> future)

      Creates a new `GroovyPromise` wrapping the given CompletableFuture.

      throws:
        NullPointerException if `future` is `null`
      Parameters:
        `future` - the backing future; must not be `null`

  - ### Method Detail

    - #### public boolean cancel()

      Attempts to cancel this computation. Delegates to CompletableFuture#cancel(boolean) CompletableFuture.cancel(true).

      Note: `CompletableFuture` cancellation sets the future's state to cancelled but does not reliably interrupt the underlying thread. Async work already in progress may continue running in the background. For cooperative cancellation, check Thread.isInterrupted in long-running async bodies.

      Returns:
        `true` if the future was successfully cancelled

    - #### public Awaitable<T> exceptionally(Function<Throwable, ? extends T> fn)

      Returns a new `Awaitable` that, if this one completes exceptionally, applies the given function to the exception to produce a recovery value. The throwable passed to the function is deeply unwrapped to strip JDK wrapper layers.

      Parameters:
        `fn` - the recovery function
      Returns:
        a new awaitable that recovers from failures

      Returns a new `GroovyPromise` that handles exceptions thrown by this promise. The throwable passed to the handler is deeply unwrapped to strip JDK wrapper layers (`CompletionException`, `ExecutionException`). The handler runs with the `AsyncContext` snapshot that was active when the recovery continuation was registered.

    - #### public T get()

      Blocks until the computation completes and returns the result.

      throws:
        InterruptedException if the calling thread is interrupted while waiting
      throws:
        ExecutionException if the computation completed exceptionally
      Returns:
        the computed result

      Includes a synchronous completion fast-path: if the underlying CompletableFuture is already done, the result is extracted via CompletableFuture.join which avoids the full park/unpark machinery of CompletableFuture.get. This optimisation provides a synchronous completion fast-path and eliminates unnecessary thread state transitions on the hot path where async operations complete before being awaited.

      If the future was cancelled, the original CancellationException is unwrapped from the JDK 23+ wrapper for cross-version consistency.

    - #### public T get(long timeout, TimeUnit unit)

      Blocks until the computation completes or the timeout expires.

      throws:
        InterruptedException if the calling thread is interrupted while waiting
      throws:
        ExecutionException if the computation completed exceptionally
      throws:
        TimeoutException if the wait timed out
      Parameters:
        `timeout` - the maximum time to wait
        `unit` - the time unit of the timeout argument
      Returns:
        the computed result

      Includes a synchronous completion fast-path for already-done futures, consistent with the zero-argument get() overload. Unwraps JDK 23+ CancellationException wrappers for consistency.

    - #### public boolean isCancelled()

      Returns `true` if the computation was cancelled before completing normally.

      Returns:
        `true` if cancelled

    - #### public boolean isCompletedExceptionally()

      Returns `true` if this computation completed exceptionally (including cancellation).

      Returns:
        `true` if completed with an error or cancellation

    - #### public boolean isDone()

      Returns `true` if the computation has completed (normally, exceptionally, or via cancellation).

      Returns:
        `true` if complete

    - #### <T> public static GroovyPromise<T> of(CompletableFuture<T> future)

      Creates a `GroovyPromise` wrapping the given CompletableFuture.

      This is a convenience factory that delegates to GroovyPromise(CompletableFuture).

      throws:
        NullPointerException if `future` is `null`
      Parameters:
        `future` - the backing future; must not be `null`
      Type Parameters:
        `T` - the result type
      Returns:
        a new `GroovyPromise` wrapping `future`

    - #### <U> public Awaitable<U> then(Function<? super T, ? extends U> fn)

      Returns a new `Awaitable` whose result is obtained by applying the given function to this awaitable's result when it completes.

      Parameters:
        `fn` - the mapping function
      Type Parameters:
        `U` - the type of the mapped result
      Returns:
        a new awaitable holding the mapped result

      Returns a new `GroovyPromise` whose result is obtained by applying the given function to this promise's result. The current `AsyncContext` snapshot is captured when the continuation is registered and restored when it executes.

    - #### <U> public Awaitable<U> thenCompose(Function<? super T, ? extends Awaitable<U>> fn)

      Returns a new `Awaitable` produced by applying the given async function to this awaitable's result, flattening the nested `Awaitable`. This is the monadic `flatMap` operation for awaitables.

      Parameters:
        `fn` - the async mapping function that returns an `Awaitable`
      Type Parameters:
        `U` - the type of the inner awaitable's result
      Returns:
        a new awaitable holding the inner result

      Returns a new `GroovyPromise` that is the result of composing this promise with the async function, enabling flat-mapping of awaitables. The current `AsyncContext` snapshot is captured when the continuation is registered and restored when it executes.

    - #### public CompletableFuture<T> toCompletableFuture()

      Converts this `Awaitable` to a JDK CompletableFuture for interoperability with APIs that require it.

      Returns:
        a `CompletableFuture` representing this computation

      Returns the underlying CompletableFuture for interop with JDK APIs.

    - #### public String toString()

      Returns a human-readable representation showing the promise state: `GroovyPromise{pending`}, `GroovyPromise{completed`}, or `GroovyPromise{failed`}.