Package: org.apache.groovy.runtime.async

## [Java] Class AsyncSupport

- org.apache.groovy.runtime.async.AsyncSupport

-     public class AsyncSupport
      extends Object

  Internal runtime support for the `async`/`await`/`defer` language features.

  This class is the entry point invoked by compiler-generated code and also exposes the combinator and configuration surface used by Awaitable. Combinator algorithms live in AwaitCombinators; executor/scheduler configuration lives in AsyncExecutors.

  Thread pool configuration:

  - On JDK 21+ the default executor is a virtual-thread-per-task executor. Virtual threads make blocking within `await()` essentially free.
  - On JDK 17-20 the fallback is a cached daemon thread pool whose maximum size is controlled by the system property `groovy.async.parallelism` (default: `256`).
  - The executor can be overridden via setExecutor; pass `null` to restore the platform default.

  Exception handling follows a transparency principle: the original exception is rethrown without being wrapped.

  See Also:
    Awaitable
  Since:
    6.0.0

- - ### Methods Summary

    Methods
    Type Params | Return Type | Name and description
    --- | --- | ---
    `<T>` | `public static List<T>` | `all(Object sources)` Waits for all given sources to complete, returning their results in order.
    `` | `public static Awaitable<List<Object>>` | `allAsync(Object sources)` Non-blocking variant of all — returns an Awaitable.
    `` | `public static List<AwaitResult<Object>>` | `allSettled(Object sources)` Waits for all sources to settle (succeed or fail), returning a list of AwaitResult without throwing.
    `` | `public static Awaitable<List<AwaitResult<Object>>>` | `allSettledAsync(Object sources)` Non-blocking variant of allSettled — returns an Awaitable.
    `<T>` | `public static T` | `any(Object sources)` Returns the result of the first source to complete (success or failure).
    `<T>` | `public static Awaitable<T>` | `anyAsync(Object sources)` Non-blocking variant of any — returns an Awaitable.
    `<T>` | `public static Awaitable<T>` | `async(Supplier<T> supplier)` Executes the given supplier asynchronously using the default executor.
    `<T>` | `public static Iterable<T>` | `asyncGenerator(Consumer<Object> body)` Starts a generator immediately, returning an Iterable backed by a GeneratorBridge.
    `<T>` | `public static T` | `await(Awaitable<T> awaitable)` Awaits the result of an Awaitable.
    `<T>` | `public static T` | `await(CompletableFuture<T> future)` Awaits a CompletableFuture using non-interruptible `join()`.
    `<T>` | `public static T` | `await(CompletionStage<T> stage)` Awaits a CompletionStage by converting to CompletableFuture.
    `<T>` | `public static T` | `await(Future<T> future)` Awaits a Future.
    `<T>` | `public static T` | `await(Object source)` Awaits an arbitrary object by adapting it via Awaitable.from.
    `` | `public static void` | `closeIterable(Object source)` Closes a source if it implements Closeable or AutoCloseable.
    `<T>` | `public static Awaitable<T>` | `completeOnTimeout(Object source, T fallback, long timeout, TimeUnit unit)` Wraps a source with a timeout that uses a fallback value instead of throwing.
    `<T>` | `public static Awaitable<T>` | `completeOnTimeoutMillis(Object source, T fallback, long millis)` Convenience: timeout in milliseconds.
    `` | `public static Deque<Callable<?>>` | `createDeferScope()` Creates a new defer scope (LIFO stack of cleanup actions).
    `` | `public static void` | `defer(Deque<Callable<?>> scope, Callable<?> action)` Registers a deferred action in the given scope.
    `` | `public static Awaitable<Void>` | `delay(long millis)` Returns an Awaitable that completes after the specified delay.
    `` | `public static Awaitable<Void>` | `delay(long duration, TimeUnit unit)` Delay with explicit time unit.
    `<T>` | `public static Awaitable<T>` | `executeAsync(Supplier<T> supplier, Executor executor)` Executes the given supplier asynchronously on the specified executor, returning an Awaitable.
    `` | `public static void` | `executeDeferScope(Deque<Callable<?>> scope)` Executes all deferred actions in LIFO order.
    `<T>` | `public static T` | `first(Object sources)` Returns the result of the first source to complete successfully.
    `<T>` | `public static Awaitable<T>` | `firstAsync(Object sources)` Non-blocking variant of first — returns an Awaitable.
    `` | `public static Executor` | `getExecutor()` Returns the current executor used for async tasks.
    `` | `public static ScheduledExecutorService` | `getScheduler()` Returns the shared scheduler for delays, timeouts, and scope deadlines.
    `<T>` | `public static Awaitable<T>` | `go(Supplier<T> supplier)` Lightweight task spawn.
    `` | `public static boolean` | `isVirtualThreadsAvailable()` Returns `true` if running on JDK 21+ with virtual thread support.
    `<T>` | `public static Awaitable<T>` | `orTimeout(Object source, long timeout, TimeUnit unit)` Wraps a source with a timeout.
    `<T>` | `public static Awaitable<T>` | `orTimeoutMillis(Object source, long millis)` Convenience: timeout in milliseconds.
    `` | `public static void` | `resetExecutor()` Resets the executor to the platform default.
    `` | `public static void` | `setExecutor(Executor executor)` Sets the executor used for async tasks.
    `<T>` | `public static Iterable<T>` | `toIterable(Object source)` Converts an arbitrary source to an Iterable for use in `for await` loops.
    `` | `public static Throwable` | `unwrap(Throwable t)` Strips JDK wrapper layers (CompletionException, ExecutionException, InvocationTargetException, UndeclaredThrowableException) to expose the original cause.
    `` | `public static CompletionException` | `wrapForFuture(Throwable t)`
    `` | `public static void` | `yieldReturn(Object bridge, Object value)` Called by compiler-generated code for `yield return expr` inside an async generator closure.

  - ### Inherited Methods Summary

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

- - ### Method Detail

    - #### <T> public static List<T> all(Object sources)

      Waits for all given sources to complete, returning their results in order. Multi-arg `await(a, b, c)` desugars to the non-blocking allAsync(Object...) form, then awaits it.

    - #### public static Awaitable<List<Object>> allAsync(Object sources)

      Non-blocking variant of all — returns an Awaitable.

    - #### public static List<AwaitResult<Object>> allSettled(Object sources)

      Waits for all sources to settle (succeed or fail), returning a list of AwaitResult without throwing.

    - #### public static Awaitable<List<AwaitResult<Object>>> allSettledAsync(Object sources)

      Non-blocking variant of allSettled — returns an Awaitable.

    - #### <T> public static T any(Object sources)

      Returns the result of the first source to complete (success or failure).

    - #### <T> public static Awaitable<T> anyAsync(Object sources)

      Non-blocking variant of any — returns an Awaitable.

    - #### <T> @GroovyABI(since = "6.0.0")
      public static Awaitable<T> async(Supplier<T> supplier)

      Executes the given supplier asynchronously using the default executor.

    - #### <T> @GroovyABI(since = "6.0.0")
      public static Iterable<T> asyncGenerator(Consumer<Object> body)

      Starts a generator immediately, returning an Iterable backed by a GeneratorBridge. The consumer receives the bridge as its argument and should call yieldReturn to produce values.

      This is the runtime entry point for `async { ... yield return ... }` expressions. The compiler generates a closure that SAM-coerces to `Consumer<Object>`.

      Parameters:
        `body` - the generator body; receives a GeneratorBridge
      Type Parameters:
        `T` - the element type
      Returns:
        an Iterable that yields values from the generator

    - #### <T> @GroovyABI(since = "6.0.0")
      public static T await(Awaitable<T> awaitable)

      Awaits the result of an Awaitable. Blocks the calling thread until the computation completes. The original exception is rethrown transparently.

    - #### <T> @GroovyABI(since = "6.0.0")
      public static T await(CompletableFuture<T> future)

      Awaits a CompletableFuture using non-interruptible `join()`.

    - #### <T> @GroovyABI(since = "6.0.0")
      public static T await(CompletionStage<T> stage)

      Awaits a CompletionStage by converting to CompletableFuture.

    - #### <T> @GroovyABI(since = "6.0.0")
      public static T await(Future<T> future)

      Awaits a Future. Delegates to the CF overload if applicable.

    - #### <T> @GroovyABI(since = "6.0.0")
      public static T await(Object source)

      Awaits an arbitrary object by adapting it via Awaitable.from.

      This is the fallback overload called by compiler-generated `await` expressions. The compiler inserts a cast to Object so that overload resolution does not have to choose among `Awaitable`, `CompletionStage`, and `Future` when a value implements more than one of them (e.g. CompletableFuture).

    - #### @GroovyABI(since = "6.0.0")
      public static void closeIterable(Object source)

      Closes a source if it implements Closeable or AutoCloseable. Called by compiler-generated finally block in `for await` loops. Cleanup exceptions are swallowed so they cannot mask the original loop error; prefer robust `close()` implementations.

    - #### <T> public static Awaitable<T> completeOnTimeout(Object source, T fallback, long timeout, TimeUnit unit)

      Wraps a source with a timeout that uses a fallback value instead of throwing. On timeout the underlying computation is cancelled.

    - #### <T> public static Awaitable<T> completeOnTimeoutMillis(Object source, T fallback, long millis)

      Convenience: timeout in milliseconds.

    - #### @GroovyABI(since = "6.0.0")
      public static Deque<Callable<?>> createDeferScope()

      Creates a new defer scope (LIFO stack of cleanup actions). Called by compiler-generated code at the start of closures containing `defer` statements.

    - #### @GroovyABI(since = "6.0.0")
      public static void defer(Deque<Callable<?>> scope, Callable<?> action)

      Registers a deferred action in the given scope. Actions execute in LIFO order when executeDeferScope is called (in the finally block).

    - #### public static Awaitable<Void> delay(long millis)

      Returns an Awaitable that completes after the specified delay.

    - #### public static Awaitable<Void> delay(long duration, TimeUnit unit)

      Delay with explicit time unit.

    - #### <T> public static Awaitable<T> executeAsync(Supplier<T> supplier, Executor executor)

      Executes the given supplier asynchronously on the specified executor, returning an Awaitable.

    - #### public static void executeDeferScope(Deque<Callable<?>> scope)

      Executes all deferred actions in LIFO order. If multiple actions throw, subsequent exceptions are added as suppressed. If a deferred action returns a Future/Awaitable, the result is awaited before continuing.

    - #### <T> public static T first(Object sources)

      Returns the result of the first source to complete successfully. Only fails when all sources fail (aggregate CompletionException; `await` transparency rethrows the cause).

    - #### <T> public static Awaitable<T> firstAsync(Object sources)

      Non-blocking variant of first — returns an Awaitable.

    - #### public static Executor getExecutor()

      Returns the current executor used for async tasks.

    - #### public static ScheduledExecutorService getScheduler()

      Returns the shared scheduler for delays, timeouts, and scope deadlines.

    - #### <T> public static Awaitable<T> go(Supplier<T> supplier)

      Lightweight task spawn. Alias of async(Supplier) for Go-style ergonomics; semantics are identical.

    - #### public static boolean isVirtualThreadsAvailable()

      Returns `true` if running on JDK 21+ with virtual thread support.

    - #### <T> public static Awaitable<T> orTimeout(Object source, long timeout, TimeUnit unit)

      Wraps a source with a timeout. If the source does not complete within the specified time, the returned Awaitable fails with TimeoutException and the underlying computation is cancelled.

    - #### <T> public static Awaitable<T> orTimeoutMillis(Object source, long millis)

      Convenience: timeout in milliseconds.

    - #### public static void resetExecutor()

      Resets the executor to the platform default. Equivalent to `setExecutor(null)`.

    - #### public static void setExecutor(Executor executor)

      Sets the executor used for async tasks.

      Pass `null` to restore the platform default (virtual threads on JDK 21+, cached daemon pool otherwise). The change takes effect for subsequent `async` launches; in-flight tasks keep the executor that started them.

      Parameters:
        `executor` - the executor to use, or `null` to reset

    - #### <T> @GroovyABI(since = "6.0.0")
      public static Iterable<T> toIterable(Object source)

      Converts an arbitrary source to an Iterable for use in `for await` loops. Handles arrays, collections, iterables, iterators, and adapter-supported types. The returned iterable may block on `next()` for async sources.

      Parameters:
        `source` - the source to convert
      Type Parameters:
        `T` - the element type
      Returns:
        an iterable

    - #### public static Throwable unwrap(Throwable t)

      Strips JDK wrapper layers (CompletionException, ExecutionException, InvocationTargetException, UndeclaredThrowableException) to expose the original cause.

    - #### public static CompletionException wrapForFuture(Throwable t)

    - #### @GroovyABI(since = "6.0.0")
      public static void yieldReturn(Object bridge, Object value)

      Called by compiler-generated code for `yield return expr` inside an async generator closure. Delegates to the bridge's yield method.

      Parameters:
        `bridge` - the GeneratorBridge instance (injected as synthetic parameter)
        `value` - the value to yield