Package: org.codehaus.groovy.transform

## [Java] Class AsyncTransformHelper

- org.codehaus.groovy.transform.AsyncTransformHelper

-     public final class AsyncTransformHelper
      extends Object

  Shared AST utilities for the `async`/`await`/`defer` language features.

  Centralises AST node construction and higher-level rewrites used by the parser (`AstBuilder`) so feature logic does not sprawl across the visitor.

  Since:
    6.0.0

- - ### Methods Summary

    Methods
    Type Params | Return Type | Name and description
    --- | --- | ---
    `` | `public static Expression` | `buildAsyncCall(Expression closure)` Builds `AsyncSupport.async(closure)` — starts immediately, returns Awaitable.
    `` | `public static Expression` | `buildAsyncGeneratorCall(Expression closure)` Builds `AsyncSupport.asyncGenerator(closure)` — starts immediately, returns Iterable.
    `` | `public static Expression` | `buildAwaitCall(Expression arg)` Builds `AsyncSupport.await(arg)` or for multi-arg: `AsyncSupport.await(Awaitable.all(arg1, arg2, ...))`.
    `` | `public static Expression` | `buildCloseIterableCall(Expression source)` Builds `AsyncSupport.closeIterable(source)`.
    `` | `public static Expression` | `buildDeferCall(Expression action)` Builds `AsyncSupport.defer($__deferScope__, action)`.
    `` | `public static Expression` | `buildToIterableCall(Expression source)` Builds `AsyncSupport.toIterable(source)`.
    `` | `public static Expression` | `buildYieldReturnCall(Expression arg)` Builds `AsyncSupport.yieldReturn($__asyncGen__, expr)`.
    `` | `public static boolean` | `containsDefer(Statement stmt)` Returns `true` if the statement tree contains a `defer` call, without descending into nested closures.
    `` | `public static boolean` | `containsYieldReturn(Statement stmt)` Returns `true` if the statement tree contains a `yield return` call, without descending into nested closures.
    `` | `public static Parameter` | `createGenParam()` Creates the synthetic generator parameter `$__asyncGen__`.
    `` | `public static Expression` | `transformAsyncClosure(ClosureExpression closure)` Applies defer-scope wrapping and generator parameter injection to an `async { ... }` closure, then builds the runtime call (`async` or `asyncGenerator`).
    `` | `public static Statement` | `wrapForAwaitLoop(ForStatement forStatement)` Rewrites a `for await` loop into a block that materialises the source iterable, runs the loop, and closes the source in a finally block:
         var $__forAwaitSource_N = AsyncSupport.toIterable(collection)
         try {
             for (... in $__forAwaitSource_N) { body }
         } finally {
             AsyncSupport.closeIterable($__forAwaitSource_N)
         }
    `` | `public static Statement` | `wrapWithDeferScope(Statement body)` Wraps a statement block with defer scope management:
         var $__deferScope__ = AsyncSupport.createDeferScope()
         try { original body }
         finally { AsyncSupport.executeDeferScope($__deferScope__) }

  - ### Inherited Methods Summary

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

- - ### Method Detail

    - #### public static Expression buildAsyncCall(Expression closure)

      Builds `AsyncSupport.async(closure)` — starts immediately, returns Awaitable.

    - #### public static Expression buildAsyncGeneratorCall(Expression closure)

      Builds `AsyncSupport.asyncGenerator(closure)` — starts immediately, returns Iterable.

    - #### public static Expression buildAwaitCall(Expression arg)

      Builds `AsyncSupport.await(arg)` or for multi-arg: `AsyncSupport.await(Awaitable.all(arg1, arg2, ...))`.

      Single-arg form casts to Object so static/dynamic overload selection targets AsyncSupport.await, avoiding ambiguity when the argument implements multiple async interfaces (e.g. CompletableFuture implements both CompletionStage and Future).

    - #### public static Expression buildCloseIterableCall(Expression source)

      Builds `AsyncSupport.closeIterable(source)`.

    - #### public static Expression buildDeferCall(Expression action)

      Builds `AsyncSupport.defer($__deferScope__, action)`.

    - #### public static Expression buildToIterableCall(Expression source)

      Builds `AsyncSupport.toIterable(source)`.

    - #### public static Expression buildYieldReturnCall(Expression arg)

      Builds `AsyncSupport.yieldReturn($__asyncGen__, expr)`.

    - #### public static boolean containsDefer(Statement stmt)

      Returns `true` if the statement tree contains a `defer` call, without descending into nested closures.

    - #### public static boolean containsYieldReturn(Statement stmt)

      Returns `true` if the statement tree contains a `yield return` call, without descending into nested closures.

    - #### public static Parameter createGenParam()

      Creates the synthetic generator parameter `$__asyncGen__`.

    - #### public static Expression transformAsyncClosure(ClosureExpression closure)

      Applies defer-scope wrapping and generator parameter injection to an `async { ... }` closure, then builds the runtime call (`async` or `asyncGenerator`).

      Parameters:
        `closure` - the parsed async closure expression
      Returns:
        the desugared runtime call expression

    - #### public static Statement wrapForAwaitLoop(ForStatement forStatement)

      Rewrites a `for await` loop into a block that materialises the source iterable, runs the loop, and closes the source in a finally block:

           var $__forAwaitSource_N = AsyncSupport.toIterable(collection)
           try {
               for (... in $__forAwaitSource_N) { body }
           } finally {
               AsyncSupport.closeIterable($__forAwaitSource_N)
           }

      Parameters:
        `forStatement` - the for statement whose collection is the await source
      Returns:
        the rewritten statement block

    - #### public static Statement wrapWithDeferScope(Statement body)

      Wraps a statement block with defer scope management:

           var $__deferScope__ = AsyncSupport.createDeferScope()
           try { original body }
           finally { AsyncSupport.executeDeferScope($__deferScope__) }