Minor tweaks

Author: daniellansun

src/main/java/groovy/concurrent/AwaitResult.java

@@ -100,6 +100,10 @@ public T getOrElse(Function<Throwable, ? extends T> fallback) {
         return success ? value : fallback.apply(error);
     }
 
+    /**
+     * Returns a human-readable representation of this result:
+     * {@code AwaitResult.Success[value]} or {@code AwaitResult.Failure[error]}.
+     */
     @Override
     public String toString() {
         return success

src/main/java/org/apache/groovy/parser/antlr4/AstBuilder.java

@@ -1285,6 +1285,10 @@ public ClassNode visitClassDeclaration(final ClassDeclarationContext ctx) {
             throw createParsingFailedException("only sealed type declarations should have `permits` clause", ctx);
         }
 
+        if (modifierManager.containsAny(ASYNC)) {
+            throw createParsingFailedException("modifier `async` is not allowed for type declarations", modifierManager.get(ASYNC).get());
+        }
+
         int modifiers = modifierManager.getClassModifiersOpValue();
 
         boolean syntheticPublic = ((modifiers & Opcodes.ACC_SYNTHETIC) != 0);
@@ -2013,6 +2017,10 @@ public DeclarationListStatement visitVariableDeclaration(final VariableDeclarati
                         asBoolean(ctx.modifiers()) ? this.visitModifiers(ctx.modifiers()) : Collections.emptyList()
                 );
 
+        if (modifierManager.containsAny(ASYNC)) {
+            throw createParsingFailedException("modifier `async` is not allowed for variable declarations", modifierManager.get(ASYNC).get());
+        }
+
         if (asBoolean(ctx.typeNamePairs())) { // e.g. def (int a, int b) = [1, 2]
             return this.createMultiAssignmentDeclarationListStatement(ctx, modifierManager);
         }

src/main/java/org/apache/groovy/parser/antlr4/ModifierManager.java

@@ -37,6 +37,7 @@
 import java.util.stream.Collectors;
 
 import static org.apache.groovy.parser.antlr4.GroovyLangParser.ABSTRACT;
+import static org.apache.groovy.parser.antlr4.GroovyLangParser.ASYNC;
 import static org.apache.groovy.parser.antlr4.GroovyLangParser.FINAL;
 import static org.apache.groovy.parser.antlr4.GroovyLangParser.NATIVE;
 import static org.apache.groovy.parser.antlr4.GroovyLangParser.STATIC;
@@ -47,7 +48,7 @@
  */
 class ModifierManager {
     private static final Map<Class, List<Integer>> INVALID_MODIFIERS_MAP = Maps.of(
-            ConstructorNode.class, Arrays.asList(STATIC, FINAL, ABSTRACT, NATIVE),
+            ConstructorNode.class, Arrays.asList(STATIC, FINAL, ABSTRACT, NATIVE, ASYNC),
             MethodNode.class, Arrays.asList(VOLATILE/*, TRANSIENT*/) // Transient is left open for properties for legacy reasons but should be removed before ClassCompletionVerifier runs (CLASSGEN)
     );
     private AstBuilder astBuilder;

src/main/java/org/apache/groovy/runtime/async/AsyncStreamGenerator.java

@@ -175,6 +175,21 @@ public void error(Throwable t) {
         }
     }
 
+    /**
+     * {@inheritDoc}
+     * <p>
+     * Blocks the calling (consumer) thread on the {@link SynchronousQueue} until
+     * the producer offers the next element, a completion sentinel, or an error.
+     * If the stream has been {@linkplain #close() closed}, returns
+     * {@code Awaitable.of(false)} immediately without blocking.
+     * <p>
+     * The consumer thread is registered via {@code consumerThread} during the
+     * blocking call so that {@link #close()} can interrupt it if needed.
+     *
+     * @return an {@code Awaitable<Boolean>} that resolves to {@code true} if a
+     *         new element is available via {@link #getCurrent()}, or {@code false}
+     *         if the stream is exhausted or closed
+     */
     @Override
     @SuppressWarnings("unchecked")
     public Awaitable<Boolean> moveNext() {
@@ -208,6 +223,15 @@ public Awaitable<Boolean> moveNext() {
         }
     }
 
+    /**
+     * {@inheritDoc}
+     * <p>
+     * Returns the most recently consumed element. The value is updated each time
+     * {@link #moveNext()} returns {@code true}.
+     *
+     * @return the current element, or {@code null} before the first successful
+     *         {@code moveNext()} call
+     */
     @Override
     public T getCurrent() {
         return current;

src/main/java/org/apache/groovy/runtime/async/GroovyPromise.java

@@ -47,6 +47,12 @@ public class GroovyPromise<T> implements Awaitable<T> {
 
     private final CompletableFuture<T> future;
 
+    /**
+     * Creates a new {@code GroovyPromise} wrapping the given {@link CompletableFuture}.
+     *
+     * @param future the backing future; must not be {@code null}
+     * @throws NullPointerException if {@code future} is {@code null}
+     */
     public GroovyPromise(CompletableFuture<T> future) {
         this.future = Objects.requireNonNull(future, "future must not be null");
     }
@@ -58,6 +64,13 @@ public static <T> GroovyPromise<T> of(CompletableFuture<T> future) {
         return new GroovyPromise<>(future);
     }
 
+    /**
+     * {@inheritDoc}
+     * <p>
+     * Waits if necessary for the computation to complete, then retrieves its result.
+     * If the future was cancelled, the original {@link CancellationException} is
+     * unwrapped from the JDK 23+ wrapper for cross-version consistency.
+     */
     @Override
     public T get() throws InterruptedException, ExecutionException {
         try {
@@ -67,6 +80,12 @@ public T get() throws InterruptedException, ExecutionException {
         }
     }
 
+    /**
+     * {@inheritDoc}
+     * <p>
+     * Waits at most the given time for the computation to complete.
+     * Unwraps JDK 23+ {@link CancellationException} wrappers for consistency.
+     */
     @Override
     public T get(long timeout, TimeUnit unit) throws InterruptedException, ExecutionException, TimeoutException {
         try {
@@ -76,6 +95,7 @@ public T get(long timeout, TimeUnit unit) throws InterruptedException, Execution
         }
     }
 
+    /** {@inheritDoc} */
     @Override
     public boolean isDone() {
         return future.isDone();
@@ -98,26 +118,47 @@ public boolean cancel() {
         return future.cancel(true);
     }
 
+    /** {@inheritDoc} */
     @Override
     public boolean isCancelled() {
         return future.isCancelled();
     }
 
+    /** {@inheritDoc} */
     @Override
     public boolean isCompletedExceptionally() {
         return future.isCompletedExceptionally();
     }
 
+    /**
+     * {@inheritDoc}
+     * <p>
+     * Returns a new {@code GroovyPromise} whose result is obtained by applying
+     * the given function to this promise's result.
+     */
     @Override
     public <U> Awaitable<U> then(Function<? super T, ? extends U> fn) {
         return new GroovyPromise<>(future.thenApply(fn));
     }
 
+    /**
+     * {@inheritDoc}
+     * <p>
+     * Returns a new {@code GroovyPromise} that is the result of composing this
+     * promise with the async function, enabling flat-mapping of awaitables.
+     */
     @Override
     public <U> Awaitable<U> thenCompose(Function<? super T, ? extends Awaitable<U>> fn) {
         return new GroovyPromise<>(future.thenCompose(t -> fn.apply(t).toCompletableFuture()));
     }
 
+    /**
+     * {@inheritDoc}
+     * <p>
+     * Returns a new {@code GroovyPromise} that handles exceptions thrown by this promise.
+     * The throwable passed to the handler is deeply unwrapped to strip JDK
+     * wrapper layers ({@code CompletionException}, {@code ExecutionException}).
+     */
     @Override
     public Awaitable<T> exceptionally(Function<Throwable, ? extends T> fn) {
         return new GroovyPromise<>(future.exceptionally(t -> {
@@ -127,6 +168,11 @@ public Awaitable<T> exceptionally(Function<Throwable, ? extends T> fn) {
         }));
     }
 
+    /**
+     * {@inheritDoc}
+     * <p>
+     * Returns the underlying {@link CompletableFuture} for interop with JDK APIs.
+     */
     @Override
     public CompletableFuture<T> toCompletableFuture() {
         return future;
@@ -143,6 +189,11 @@ private static CancellationException unwrapCancellation(CancellationException ex
         return cause instanceof CancellationException ce ? ce : exception;
     }
 
+    /**
+     * Returns a human-readable representation showing the promise state:
+     * {@code GroovyPromise{pending}}, {@code GroovyPromise{completed}}, or
+     * {@code GroovyPromise{failed}}.
+     */
     @Override
     public String toString() {
         if (future.isDone()) {

src/spec/doc/core-async-await.adoc

@@ -382,6 +382,23 @@ each result is wrapped in an `AwaitResult` with `isSuccess()`, `isFailure()`, `v
 include::../test/AsyncAwaitSpecTest.groovy[tags=await_all_settled,indent=0]
 ----
 
+[[await-result]]
+=== `AwaitResult` — Outcome Wrapper
+
+Each element returned by `allSettled` is an `AwaitResult<T>`. This immutable value type
+carries either a success value or a failure throwable, and provides safe accessors:
+
+* `isSuccess()` / `isFailure()` — check outcome type
+* `value` — the result (throws `IllegalStateException` on failure)
+* `error` — the exception (throws `IllegalStateException` on success)
+* `getOrElse(Function)` — recover from failures with a fallback function
+* `toString()` — returns `AwaitResult.Success[value]` or `AwaitResult.Failure[error]`
+
+[source,groovy]
+----
+include::../test/AsyncAwaitSpecTest.groovy[tags=await_result_api,indent=0]
+----
+
 === Continuation Helpers
 
 Use `thenAccept`, `whenComplete`, and `handle` when you want continuation-style
@@ -415,6 +432,16 @@ provide the same capability on an existing awaitable.
 include::../test/AsyncAwaitSpecTest.groovy[tags=timeout_combinators,indent=0]
 ----
 
+==== Instance Forms: `orTimeout` and `completeOnTimeout`
+
+The instance methods `orTimeout(millis)` and `completeOnTimeout(fallback, millis)` provide
+a fluent alternative to the static `Awaitable.timeout()` and `Awaitable.timeoutOr()` forms:
+
+[source,groovy]
+----
+include::../test/AsyncAwaitSpecTest.groovy[tags=instance_timeout_methods,indent=0]
+----
+
 [[flow-publisher]]
 == `Flow.Publisher` Integration
 
@@ -638,6 +665,31 @@ lose exceptions silently:
 include::../test/AsyncAwaitSpecTest.groovy[tags=fire_and_forget,indent=0]
 ----
 
+[[inspection]]
+== Inspecting Awaitable State
+
+An `Awaitable` provides non-blocking inspection methods for checking its state without
+blocking the calling thread:
+
+* `isDone()` — `true` when the awaitable has completed (successfully, exceptionally, or via cancellation)
+* `isCancelled()` — `true` when the awaitable was cancelled via `cancel()`
+* `isCompletedExceptionally()` — `true` when the awaitable completed with an exception (including cancellation)
+
+[source,groovy]
+----
+include::../test/AsyncAwaitSpecTest.groovy[tags=inspection_methods,indent=0]
+----
+
+[[async-modifier-restrictions]]
+== `async` Modifier Restrictions
+
+The `async` keyword is valid only on **method declarations** (including script-level methods)
+and **closure/lambda expressions**. Applying `async` to other declarations is a compile-time error:
+
+* **Class/interface declarations**: `async class Foo {}` → parser error
+* **Field/variable declarations**: `async def x = 1` → compilation error ("async not allowed for variable declarations")
+* **Constructor declarations**: `async Foo() {}` → compilation error ("async not allowed for constructors")
+
 [[implementation-details]]
 == Implementation Notes
 
@@ -899,4 +951,13 @@ JavaScript, C#, Kotlin, and Swift, for developers familiar with those languages.
 
 | Annotation form
 | `@Async def methodName() { ... }`
+
+| Inspection
+| `awaitable.isDone()` / `isCancelled()` / `isCompletedExceptionally()`
+
+| Timeout (instance)
+| `awaitable.orTimeout(ms)` / `awaitable.completeOnTimeout(fallback, ms)`
+
+| AwaitResult
+| `result.isSuccess()` / `result.isFailure()` / `result.getOrElse { fallback }`
 |===