[
https://issues.apache.org/jira/browse/GROOVY-9381?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=18071193#comment-18071193
]
ASF GitHub Bot commented on GROOVY-9381:
----------------------------------------
Copilot commented on code in PR #2437:
URL: https://github.com/apache/groovy/pull/2437#discussion_r3036748295
##########
src/main/java/org/apache/groovy/runtime/async/AsyncSupport.java:
##########
@@ -0,0 +1,741 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.groovy.runtime.async;
+
+import groovy.concurrent.AwaitResult;
+import groovy.concurrent.Awaitable;
+import groovy.lang.Closure;
+
+import java.lang.invoke.MethodHandle;
+import java.lang.invoke.MethodHandles;
+import java.lang.invoke.MethodType;
+import java.util.ArrayDeque;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.Deque;
+import java.util.Iterator;
+import java.util.List;
+import java.util.Objects;
+import java.util.concurrent.CancellationException;
+import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.CompletionException;
+import java.util.concurrent.CompletionStage;
+import java.util.concurrent.ExecutionException;
+import java.util.concurrent.Executor;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import java.util.concurrent.Future;
+import java.util.concurrent.ScheduledExecutorService;
+import java.util.concurrent.ScheduledFuture;
+import java.util.concurrent.SynchronousQueue;
+import java.util.concurrent.ThreadPoolExecutor;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.TimeoutException;
+
+/**
+ * Internal runtime support for the {@code async}/{@code await}/{@code defer}
language features.
+ * <p>
+ * This class contains the actual implementation invoked by compiler-generated
code.
+ * User code should prefer the static methods on {@link
groovy.concurrent.Awaitable}
+ * for combinators and configuration.
+ * <p>
+ * <b>Thread pool configuration:</b>
+ * <ul>
+ * <li>On JDK 21+ the default executor is a virtual-thread-per-task executor.
+ * Virtual threads make blocking within {@code await()} essentially
free.</li>
+ * <li>On JDK 17-20 the fallback is a cached daemon thread pool
+ * whose maximum size is controlled by the system property
+ * {@code groovy.async.parallelism} (default: {@code 256}).</li>
+ * <li>The executor can be overridden at any time via {@link
#setExecutor}.</li>
+ * </ul>
+ * <p>
+ * <b>Exception handling</b> follows a transparency principle: the
+ * <em>original</em> exception is rethrown without being wrapped.
+ *
+ * @see groovy.concurrent.Awaitable
+ * @since 6.0.0
+ */
+public class AsyncSupport {
+
+ private static final boolean VIRTUAL_THREADS_AVAILABLE;
+ private static final Executor VIRTUAL_THREAD_EXECUTOR;
+ private static final int FALLBACK_MAX_THREADS;
+ private static final Executor FALLBACK_EXECUTOR;
+
+ static {
+ Executor vtExecutor = null;
+ boolean vtAvailable = false;
+ try {
+ MethodHandle mh = MethodHandles.lookup().findStatic(
+ Executors.class, "newVirtualThreadPerTaskExecutor",
+ MethodType.methodType(ExecutorService.class));
+ vtExecutor = (Executor) mh.invoke();
+ vtAvailable = true;
+ } catch (Throwable ignored) {
+ // JDK < 21 — virtual threads not available
+ }
+ VIRTUAL_THREAD_EXECUTOR = vtExecutor;
+ VIRTUAL_THREADS_AVAILABLE = vtAvailable;
+
+ FALLBACK_MAX_THREADS =
org.apache.groovy.util.SystemUtil.getIntegerSafe(
+ "groovy.async.parallelism", 256);
+ if (!VIRTUAL_THREADS_AVAILABLE) {
+ FALLBACK_EXECUTOR = new ThreadPoolExecutor(
+ 0, FALLBACK_MAX_THREADS,
+ 60L, TimeUnit.SECONDS,
+ new SynchronousQueue<>(),
+ r -> {
+ Thread t = new Thread(r);
+ t.setDaemon(true);
+ t.setName("groovy-async-" + t.getId());
+ return t;
+ },
+ new ThreadPoolExecutor.CallerRunsPolicy());
+ } else {
+ FALLBACK_EXECUTOR = null;
+ }
+ }
+
+ private static volatile Executor defaultExecutor =
+ VIRTUAL_THREADS_AVAILABLE ? VIRTUAL_THREAD_EXECUTOR :
FALLBACK_EXECUTOR;
+
+ private static final ScheduledExecutorService SCHEDULER =
+ Executors.newSingleThreadScheduledExecutor(r -> {
+ Thread t = new Thread(r, "groovy-async-scheduler");
+ t.setDaemon(true);
+ return t;
+ });
+
+ private AsyncSupport() { }
+
+ // --
> Add native async/await support
> ------------------------------
>
> Key: GROOVY-9381
> URL: https://issues.apache.org/jira/browse/GROOVY-9381
> Project: Groovy
> Issue Type: New Feature
> Reporter: Daniel Sun
> Priority: Major
>
> h2. Summary
> Introduce first-class {{{}async{}}}/{{{}await{}}} language support to Groovy,
> enabling developers to write asynchronous code in a sequential, readable
> style — on par with the async/await facilities in JavaScript (ES2017), C#
> (5.0), Kotlin (coroutines), and Swift (5.5).
> h2. Motivation
> Modern JVM applications are overwhelmingly concurrent. Web services, data
> pipelines, and reactive systems spend most of their time waiting for network
> I/O, database queries, or downstream services. The JVM offers powerful but
> low-level concurrency primitives ({{{}CompletableFuture{}}},
> {{{}Flow.Publisher{}}}, {{{}ExecutorService{}}}), and while libraries like
> RxJava and Project Reactor raise the abstraction level, they introduce their
> own learning curve and cannot alter the language's control-flow syntax.
> Today, a typical three-step async workflow in Groovy looks like this:
> {code:groovy}
> CompletableFuture.supplyAsync { fetchUserId() }
> .thenCompose { id -> CompletableFuture.supplyAsync { lookupName(id) } }
> .thenCompose { name -> CompletableFuture.supplyAsync { loadProfile(name)
> } }
> .exceptionally { ex -> handleError(ex) }
> {code}
> The business logic is obscured by plumbing. Exception handling is decoupled
> from the code that raises exceptions, and the control flow reads inside-out.
> With the proposed {{{}async{}}}/{{{}await{}}}, the same logic becomes:
> {code:groovy}
> async fetchProfile() {
> def id = await fetchUserIdAsync()
> def name = await lookupNameAsync(id)
> return await loadProfileAsync(name)
> }
> {code}
> This reads identically to synchronous code. Standard
> {{{}try{}}}/{{{}catch{}}}, {{{}for{}}}, {{{}if{}}}, and variable assignment
> all compose naturally — no callbacks, no chained lambdas.
> h2. Scope
> This proposal introduces the following language constructs and runtime APIs:
> h3. Language Constructs
> ||Construct||Syntax||Description||
> |Async method|async ReturnType methodName(params) \{ ... }|Declares a method
> that executes asynchronously and returns {{Awaitable<T>}}|
> |Await expression|{{await expr}} / {{await(expr)}}|Suspends the enclosing
> async context until the awaited computation completes; transparently unwraps
> the result|
> |Async closure / lambda|async \{ params -> body } / async (params) -> \{ body
> }|Creates a reusable asynchronous function (must be explicitly invoked to
> start execution)|
> |For-await loop|for await (item in source) \{ ... }|Iterates over an
> {{{}AsyncStream{}}}, {{{}Flow.Publisher{}}}, or {{{}Iterable{}}}, resolving
> each element asynchronously|
> |Yield return|{{yield return expr}}|Emits a value from an async generator
> method, producing an {{AsyncStream<T>}} with natural back-pressure|
> |Defer|defer \{ cleanup } / {{defer cleanup}}|Schedules a cleanup block to
> execute on method exit (LIFO order), inspired by Go's {{defer}}|
> |@Async annotation|{{@Async}} on method declarations|Annotation equivalent of
> the {{async}} keyword modifier, for interoperability with
> annotation-processing tools|
> h3. Public API ({{{}groovy.concurrent{}}} package)
> ||Class/Interface||Role||
> |{{Awaitable<T>}}|Core promise abstraction (analogous to C#'s {{Task<T>}} /
> JS's {{{}Promise<T>{}}}). Provides static combinators ({{{}all{}}},
> {{{}any{}}}, {{{}allSettled{}}}, {{{}delay{}}}, {{{}timeout{}}},
> {{{}timeoutOr{}}}), factories ({{{}of{}}}, {{{}failed{}}}), and instance
> continuation methods ({{{}then{}}}, {{{}thenCompose{}}},
> {{{}exceptionally{}}}, {{{}orTimeout{}}}, {{{}completeOnTimeout{}}})|
> |{{AsyncStream<T>}}|Asynchronous iteration abstraction (analogous to C#'s
> {{{}IAsyncEnumerable<T>{}}}). Supports
> {{{}moveNext(){}}}/{{{}getCurrent(){}}} pull-based consumption with
> {{AutoCloseable}} semantics|
> |{{AwaitResult<T>}}|Outcome wrapper returned by {{allSettled()}} — carries
> either a success value or a failure throwable|
> |{{AwaitableAdapter}}|SPI interface for adapting third-party async types
> (RxJava, Reactor, Spring) to {{{}Awaitable{}}}/{{{}AsyncStream{}}}|
> |{{AwaitableAdapterRegistry}}|Central adapter registry with {{ServiceLoader}}
> auto-discovery and runtime registration|
> h3. Internal Runtime ({{{}org.apache.groovy.runtime.async{}}} package)
> ||Class||Role||
> |{{AsyncSupport}}|Central runtime entry point — all {{await}} overloads,
> {{async}} execution, {{defer}} scope management, combinator implementation,
> timeout scheduling, {{yield return}} dispatch|
> |{{GroovyPromise<T>}}|Default {{Awaitable}} implementation backed by
> {{{}CompletableFuture{}}}. Sole bridge between the public API and JDK async
> infrastructure|
> |{{AsyncStreamGenerator<T>}}|Producer/consumer {{AsyncStream}} implementation
> using {{SynchronousQueue}} for zero-buffered back-pressure with cooperative
> cancellation via thread tracking|
> h2. Design Principles
> # *Readability first.* Async code should be visually indistinguishable from
> synchronous code. All standard Groovy control-flow constructs
> ({{{}try{}}}/{{{}catch{}}}, {{{}for{}}}, {{{}if{}}}/{{{}else{}}}, closures)
> must work naturally inside async methods.
> # *Exception transparency.* {{await}} automatically unwraps
> {{{}CompletionException{}}}, {{{}ExecutionException{}}}, and other JVM
> wrapper layers. The original exception type, message, and stack trace are
> preserved — callers see the same exceptions they would in synchronous code.
> # *API decoupling.* User code depends on {{{}Awaitable{}}}, not on
> {{{}CompletableFuture{}}}. The public API ({{{}groovy.concurrent{}}}) is
> separated from the internal implementation
> ({{{}org.apache.groovy.runtime.async{}}}). If the JDK's async infrastructure
> evolves (e.g., structured concurrency), only the internal layer changes.
> # *Minimal grammar footprint.* {{{}async{}}}, {{{}await{}}}, {{{}defer{}}},
> and {{yield}} are contextual keywords — they remain valid identifiers in
> non-async contexts, preserving backward compatibility. Grammar changes to
> {{GroovyLexer.g4}} and {{GroovyParser.g4}} are minimal.
> # *Thread safety is the framework's responsibility.* All concurrency control
> (atomics, volatile, CAS) is encapsulated in the runtime. Application code
> never needs explicit locks, synchronization, or volatile annotations.
> # *JVM ecosystem integration.* Built-in adapters handle
> {{{}CompletableFuture{}}}, {{{}CompletionStage{}}}, {{{}Future{}}}, and
> {{Flow.Publisher}} out of the box. Third-party frameworks integrate via the
> {{AwaitableAdapterRegistry}} SPI.
> h2. Execution Model
> On {*}JDK 21+{*}, each {{async}} method runs on a virtual thread. When the
> thread blocks on {{{}await{}}}, the JVM parks the virtual thread and releases
> the carrier (OS) thread. This achieves the practical scalability of
> compiler-generated state machines (as in C# and Kotlin) without requiring
> control-flow rewriting — stack traces remain complete, and standard debuggers
> work unmodified.
> On {*}JDK 17–20{*}, a bounded cached thread pool (default 256, configurable
> via {{{}groovy.async.parallelism{}}}) with a caller-runs back-pressure policy
> provides stable performance.
> The executor is fully configurable at runtime via
> {{{}Awaitable.setExecutor(executor){}}}.
> h2. Key Features in Detail
> h3. Combinators
> ||Method||Analogy||Behavior||
> |{{Awaitable.all(a, b, c)}}|{{Promise.all()}} / {{Task.WhenAll()}}|Waits for
> all; fails fast on first error|
> |{{Awaitable.any(a, b)}}|{{Promise.race()}} / {{Task.WhenAny()}}|Returns the
> first to complete|
> |{{Awaitable.allSettled(a, b)}}|{{Promise.allSettled()}}|Waits for all;
> captures both successes and failures in {{AwaitResult}} list|
> |{{Awaitable.delay(ms)}}|{{Task.Delay()}} / {{setTimeout}}|Non-blocking timer|
> |{{Awaitable.timeout(source, ms)}}|{{withTimeout}}|Fails with
> {{TimeoutException}} on expiry|
> |{{Awaitable.timeoutOr(source, fallback, ms)}}|—|Completes with fallback
> value on expiry|
> h3. Async Generators and Back-Pressure
> Methods containing {{yield return}} produce an {{{}AsyncStream<T>{}}},
> consumable via {{{}for await{}}}. The producer and consumer coordinate
> through a {{SynchronousQueue}} — the producer blocks on each {{yield return}}
> until the consumer pulls the next element, providing natural back-pressure
> without unbounded buffering. If the consumer exits early ({{{}break{}}},
> {{{}return{}}}, exception), the producer thread is interrupted via
> cooperative cancellation, preventing resource leaks.
> h3. Defer (Go-Style Cleanup)
> The {{defer}} keyword schedules cleanup actions that execute in LIFO order
> when the enclosing method returns, regardless of success or failure. If
> multiple deferred blocks throw, the first exception is primary and subsequent
> ones are attached via {{{}addSuppressed(){}}}. This provides deterministic
> resource cleanup without deeply nested {{{}try{}}}/{{{}finally{}}} blocks.
> h3. Adapter Registry (Third-Party Integration)
> The {{AwaitableAdapterRegistry}} is an SPI-based extension point. Adapters
> can be registered:
> * At class-load time via {{ServiceLoader}}
> ({{{}META-INF/services/groovy.concurrent.AwaitableAdapter{}}})
> * At runtime via {{AwaitableAdapterRegistry.register(adapter)}}
> This enables {{await}} to work transparently with RxJava
> {{{}Single{}}}/{{{}Observable{}}}, Reactor {{{}Mono{}}}/{{{}Flux{}}}, Spring
> {{{}ListenableFuture{}}}, or any custom async type — a single {{await}}
> keyword, regardless of the underlying library.
> h2. Thread Safety Mechanisms
> All concurrency control is internal and transparent to users:
> * *Lock-free synchronization* — {{volatile}} fields, {{{}AtomicBoolean{}}},
> {{{}AtomicReference{}}}, {{CopyOnWriteArrayList}} used throughout; no
> {{synchronized}} blocks
> * *TOCTOU prevention* — {{AsyncStreamGenerator.moveNext()}} employs a
> double-check pattern after registering the consumer thread, closing a race
> window with concurrent {{close()}}
> * *Cooperative cancellation* — {{close()}} atomically sets a closed flag and
> interrupts both producer and consumer threads via tracked
> {{AtomicReference<Thread>}}
> * *Signal delivery under interrupt* — If {{{}complete(){}}}/{{{}error(){}}}
> is interrupted and the non-blocking fallback fails, the generator
> force-closes to prevent consumer thread leak
> * *Idempotent close* — All close operations use {{compareAndSet}} and are
> safe to call multiple times from any thread
> h2. Cross-Language Comparison
> ||Aspect||Groovy||JavaScript||C#||Kotlin||Swift||
> |Async declaration|async foo() \{ }|{{async function foo()}}|{{async Task<T>
> Foo()}}|{{suspend fun foo(): T}}|{{func foo() async throws -> T}}|
> |Await|{{await expr}}|{{await expr}}|{{await
> expr}}|{{deferred.await()}}|{{try await expr}}|
> |Async iteration|{{for await (x in src)}}|{{for await (x of src)}}|{{await
> foreach (x in src)}}|manual ({{{}Flow.collect{}}})|{{for try await x in seq}}|
> |Async generator|{{yield return expr}}|{{yield}} in {{async
> function*}}|{{yield return}} in {{IAsyncEnumerable}}|flow \{ emit( x )
> }|AsyncStream \{ yield( x ) }|
> |Defer|{{defer}}|_(none)_|{{await using}}|{{use}}|{{defer}}|
> |Implementation|Thread-per-task (VT on 21+)|Event loop|State
> machine|Coroutine SM|Async SM|
> h2. Backward Compatibility
> * {{{}async{}}}, {{{}await{}}}, {{{}defer{}}}, and {{yield}} are *contextual
> keywords* — they act as keywords only in specific syntactic positions and
> remain valid identifiers elsewhere. Existing code using these as variable
> names, method names, or field names continues to compile and run without
> modification.
> * No existing public APIs are modified or removed.
> * The feature is purely additive: code that does not use
> {{{}async{}}}/{{{}await{}}} is entirely unaffected.
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
