Package org.codehaus.groovy.transform

# Class AsyncTransformHelper

java.lang.Object
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

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static Expression`
  `buildAsyncCall(Expression closure)`
  Builds `AsyncSupport.async(closure)` — starts immediately, returns Awaitable.
  `static Expression`
  `buildAsyncGeneratorCall(Expression closure)`
  Builds `AsyncSupport.asyncGenerator(closure)` — starts immediately, returns Iterable.
  `static Expression`
  `buildAwaitCall(Expression arg)`
  Builds `AsyncSupport.await(arg)` or for multi-arg: `AsyncSupport.await(Awaitable.all(arg1, arg2, ...))`.
  `static Expression`
  `buildCloseIterableCall(Expression source)`
  Builds `AsyncSupport.closeIterable(source)`.
  `static Expression`
  `buildDeferCall(Expression action)`
  Builds `AsyncSupport.defer($__deferScope__, action)`.
  `static Expression`
  `buildToIterableCall(Expression source)`
  Builds `AsyncSupport.toIterable(source)`.
  `static Expression`
  `buildYieldReturnCall(Expression arg)`
  Builds `AsyncSupport.yieldReturn($__asyncGen__, expr)`.
  `static boolean`
  `containsDefer(Statement stmt)`
  Returns `true` if the statement tree contains a `defer` call, without descending into nested closures.
  `static boolean`
  `containsYieldReturn(Statement stmt)`
  Returns `true` if the statement tree contains a `yield return` call, without descending into nested closures.
  `static Parameter`
  `createGenParam()`
  Creates the synthetic generator parameter `$__asyncGen__`.
  `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`).
  `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:
  `static Statement`
  `wrapWithDeferScope(Statement body)`
  Wraps a statement block with defer scope management:

  ### Methods inherited from class java.lang.Object

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

- ## Method Details

  - ### buildAwaitCall

    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(Object)`, avoiding ambiguity when the argument implements multiple async interfaces (e.g. `CompletableFuture` implements both `CompletionStage` and `Future`).

  - ### buildDeferCall

    public static Expression buildDeferCall(Expression action)
    Builds `AsyncSupport.defer($__deferScope__, action)`.

  - ### buildYieldReturnCall

    public static Expression buildYieldReturnCall(Expression arg)
    Builds `AsyncSupport.yieldReturn($__asyncGen__, expr)`.

  - ### buildAsyncCall

    public static Expression buildAsyncCall(Expression closure)
    Builds `AsyncSupport.async(closure)` — starts immediately, returns Awaitable.

  - ### buildAsyncGeneratorCall

    public static Expression buildAsyncGeneratorCall(Expression closure)
    Builds `AsyncSupport.asyncGenerator(closure)` — starts immediately, returns Iterable.

  - ### buildToIterableCall

    public static Expression buildToIterableCall(Expression source)
    Builds `AsyncSupport.toIterable(source)`.

  - ### buildCloseIterableCall

    public static Expression buildCloseIterableCall(Expression source)
    Builds `AsyncSupport.closeIterable(source)`.

  - ### createGenParam

    public static Parameter createGenParam()
    Creates the synthetic generator parameter `$__asyncGen__`.

  - ### containsYieldReturn

    public static boolean containsYieldReturn(Statement stmt)
    Returns `true` if the statement tree contains a `yield return` call, without descending into nested closures.

  - ### containsDefer

    public static boolean containsDefer(Statement stmt)
    Returns `true` if the statement tree contains a `defer` call, without descending into nested closures.

  - ### wrapWithDeferScope

    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__) }

  - ### wrapForAwaitLoop

    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

  - ### transformAsyncClosure

    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