Minor tweaks

Author: daniellansun

src/main/java/groovy/concurrent/AsyncStream.java

@@ -75,6 +75,36 @@ public interface AsyncStream<T> extends AutoCloseable {
     default void close() {
     }
 
+    /**
+     * Converts the given source to an {@code AsyncStream}.
+     * <p>
+     * If the source is already an {@code AsyncStream}, it is returned as-is.
+     * Otherwise, the {@link AwaitableAdapterRegistry} is consulted to find a
+     * suitable adapter. Built-in adapters handle {@link Iterable} and
+     * {@link java.util.Iterator}; the auto-discovered {@code FlowPublisherAdapter}
+     * handles {@link java.util.concurrent.Flow.Publisher}; third-party frameworks
+     * can register additional adapters via the registry.
+     * <p>
+     * This is the recommended entry point for converting external collection or
+     * reactive types to {@code AsyncStream}:
+     * <pre>
+     * AsyncStream&lt;String&gt; stream = AsyncStream.from(myList)
+     * AsyncStream&lt;Integer&gt; stream2 = AsyncStream.from(myFlowPublisher)
+     * </pre>
+     *
+     * @param source the source object; must not be {@code null}
+     * @param <T>    the element type
+     * @return an async stream backed by the source
+     * @throws IllegalArgumentException if {@code source} is {@code null}
+     *         or no adapter supports the source type
+     * @see AwaitableAdapterRegistry#toAsyncStream(Object)
+     * @since 6.0.0
+     */
+    @SuppressWarnings("unchecked")
+    static <T> AsyncStream<T> from(Object source) {
+        return AwaitableAdapterRegistry.toAsyncStream(source);
+    }
+
     /**
      * Returns an empty {@code AsyncStream} that completes immediately.
      */

src/main/java/groovy/concurrent/Awaitable.java

@@ -54,14 +54,18 @@
  *       {@code Promise.allSettled()}</li>
  *   <li>{@link #delay(long) Awaitable.delay(ms)} — like
  *       {@code Task.Delay()} / {@code setTimeout}</li>
- *   <li>{@link #timeout(Object, long) Awaitable.timeout(task, ms)} — like
+ *   <li>{@link #orTimeoutMillis(Object, long) Awaitable.orTimeoutMillis(task, ms)} — like
  *       Kotlin's {@code withTimeout} or a JavaScript promise raced against a timer</li>
- *   <li>{@link #timeoutOr(Object, Object, long) Awaitable.timeoutOr(task, fallback, ms)} —
+ *   <li>{@link #completeOnTimeoutMillis(Object, Object, long)
+ *       Awaitable.completeOnTimeoutMillis(task, fallback, ms)} —
  *       like a timeout with fallback/default value</li>
  * </ul>
  * <p>
- * <b>Static factories:</b>
+ * <b>Static factories and conversion:</b>
  * <ul>
+ *   <li>{@link #from(Object) Awaitable.from(source)} — converts any supported
+ *       async type (CompletableFuture, CompletionStage, Future, Flow.Publisher, etc.)
+ *       to an {@code Awaitable}</li>
  *   <li>{@link #of(Object) Awaitable.of(value)} — like
  *       {@code Task.FromResult()} / {@code Promise.resolve()}</li>
  *   <li>{@link #failed(Throwable) Awaitable.failed(error)} — like
@@ -297,6 +301,35 @@ default Awaitable<T> completeOnTimeout(T fallback, long duration, TimeUnit unit)
 
     // ---- Static factories ----
 
+    /**
+     * Converts the given source to an {@code Awaitable}.
+     * <p>
+     * If the source is already an {@code Awaitable}, it is returned as-is.
+     * Otherwise, the {@link AwaitableAdapterRegistry} is consulted to find a
+     * suitable adapter. Built-in adapters handle {@link CompletableFuture},
+     * {@link java.util.concurrent.CompletionStage}, {@link java.util.concurrent.Future},
+     * and {@link java.util.concurrent.Flow.Publisher}; third-party frameworks
+     * can register additional adapters via the registry.
+     * <p>
+     * This is the recommended entry point for converting external async types
+     * to {@code Awaitable}:
+     * <pre>
+     * Awaitable&lt;String&gt; aw = Awaitable.from(someCompletableFuture)
+     * Awaitable&lt;Integer&gt; aw2 = Awaitable.from(someReactorMono)
+     * </pre>
+     *
+     * @param source the source object; must not be {@code null}
+     * @param <T>    the result type
+     * @return an awaitable backed by the source
+     * @throws IllegalArgumentException if {@code source} is {@code null}
+     *         or no adapter supports the source type
+     * @see AwaitableAdapterRegistry#toAwaitable(Object)
+     * @since 6.0.0
+     */
+    static <T> Awaitable<T> from(Object source) {
+        return AwaitableAdapterRegistry.toAwaitable(source);
+    }
+
     /**
      * Returns an already-completed {@code Awaitable} with the given value.
      * Analogous to C#'s {@code Task.FromResult()} or JavaScript's

src/main/java/groovy/concurrent/AwaitableAdapterRegistry.java

@@ -111,13 +111,18 @@ public static void setBlockingExecutor(Executor executor) {
     /**
      * Converts the given source to an {@link Awaitable}.
      * If the source is already an {@code Awaitable}, it is returned as-is.
+     * <p>
+     * <b>Tip:</b> user code should generally prefer {@link Awaitable#from(Object)},
+     * which delegates to this method but is more discoverable from the
+     * {@code Awaitable} type itself.
      *
      * @param source the source object; must not be {@code null}
      * @throws IllegalArgumentException if {@code source} is {@code null}
      *         or no adapter supports the source type
+     * @see Awaitable#from(Object)
      */
     @SuppressWarnings("unchecked")
-    public static <T> Awaitable<T> toAwaitable(Object source) {
+    static <T> Awaitable<T> toAwaitable(Object source) {
         if (source == null) {
             throw new IllegalArgumentException("Cannot convert null to Awaitable");
         }
@@ -136,13 +141,18 @@ public static <T> Awaitable<T> toAwaitable(Object source) {
     /**
      * Converts the given source to an {@link AsyncStream}.
      * If the source is already an {@code AsyncStream}, it is returned as-is.
+     * <p>
+     * <b>Tip:</b> user code should generally prefer {@link AsyncStream#from(Object)},
+     * which delegates to this method but is more discoverable from the
+     * {@code AsyncStream} type itself.
      *
      * @param source the source object; must not be {@code null}
      * @throws IllegalArgumentException if {@code source} is {@code null}
      *         or no adapter supports the source type
+     * @see AsyncStream#from(Object)
      */
     @SuppressWarnings("unchecked")
-    public static <T> AsyncStream<T> toAsyncStream(Object source) {
+    static <T> AsyncStream<T> toAsyncStream(Object source) {
         if (source == null) {
             throw new IllegalArgumentException("Cannot convert null to AsyncStream");
         }

src/main/java/groovy/transform/Async.java

@@ -107,7 +107,9 @@
  * <ul>
  *   <li>Cannot be applied to abstract methods</li>
  *   <li>Cannot be applied to constructors</li>
- *   <li>Cannot be applied to methods that already return {@code Awaitable}</li>
+ *   <li>Cannot be applied to methods that already return an async type
+ *       ({@code Awaitable}, {@code AsyncStream}, {@code CompletableFuture},
+ *       {@code CompletionStage}, or {@code Future})</li>
  * </ul>
  *
  * @see groovy.concurrent.Awaitable

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

@@ -21,7 +21,6 @@
 import groovy.concurrent.AsyncStream;
 import groovy.concurrent.AwaitResult;
 import groovy.concurrent.Awaitable;
-import groovy.concurrent.AwaitableAdapterRegistry;
 import groovy.lang.Closure;
 
 import java.lang.invoke.MethodHandle;
@@ -64,8 +63,9 @@
  * <ul>
  *   <li><b>Async execution</b> — {@code executeAsync()}, {@code executeAsyncVoid()},
  *       and {@code wrapAsync()} run closures on the configured executor</li>
- *   <li><b>Await</b> — all {@code await()} overloads go through the
- *       {@link AwaitableAdapterRegistry} so that third-party async types
+ *   <li><b>Await</b> — all {@code await()} overloads use
+ *       {@link groovy.concurrent.Awaitable#from(Object) Awaitable.from()} so
+ *       that third-party async types
  *       (RxJava {@code Single}, Reactor {@code Mono}, etc.) are supported
  *       transparently once an adapter is registered</li>
  *   <li><b>Async generators</b> — {@code generateAsyncStream()} manages the
@@ -112,7 +112,6 @@
  *
  * @see groovy.concurrent.Awaitable
  * @see groovy.transform.Async
- * @see Awaitable
  * @since 6.0.0
  */
 public class AsyncSupport {
@@ -267,8 +266,8 @@ public static <T> T await(Future<T> future) {
     }
 
     /**
-     * Awaits an arbitrary object by adapting it to {@link Awaitable} via the
-     * {@link AwaitableAdapterRegistry}.  This is the fallback overload called
+     * Awaits an arbitrary object by adapting it to {@link Awaitable} via
+     * {@link Awaitable#from(Object)}.  This is the fallback overload called
      * by the {@code await} expression when the compile-time type is not one
      * of the other supported types.  Returns {@code null} for a {@code null}
      * argument.
@@ -285,7 +284,7 @@ public static <T> T await(Object source) {
         if (source instanceof CompletionStage) return await((CompletionStage<T>) source);
         if (source instanceof Future) return await((Future<T>) source);
         if (source instanceof Closure) return awaitClosure((Closure<?>) source);
-        return await(AwaitableAdapterRegistry.<T>toAwaitable(source));
+        return await(Awaitable.<T>from(source));
     }
 
     /**
@@ -543,7 +542,7 @@ private static CompletableFuture<?> toCompletableFuture(Object source) {
         if (source instanceof CompletableFuture<?> cf) return cf;
         if (source instanceof Awaitable<?> a) return a.toCompletableFuture();
         if (source instanceof CompletionStage<?> cs) return cs.toCompletableFuture();
-        return AwaitableAdapterRegistry.toAwaitable(source).toCompletableFuture();
+        return Awaitable.from(source).toCompletableFuture();
     }
 
     // ---- non-blocking combinators (return Awaitable) --------------------
@@ -813,7 +812,7 @@ public static Awaitable<Void> delay(long duration, TimeUnit unit) {
     public static <T> AsyncStream<T> toAsyncStream(Object source) {
         if (source == null) return AsyncStream.empty();
         if (source instanceof AsyncStream) return (AsyncStream<T>) source;
-        return AwaitableAdapterRegistry.toAsyncStream(source);
+        return AsyncStream.from(source);
     }
 
     /**

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

@@ -638,6 +638,24 @@ This is conceptually similar to JavaScript async iterators' `return()`, C#'s
 [[adapter-registry]]
 == Adapter Registry
 
+=== Converting External Types with `from()`
+
+The `Awaitable.from(source)` and `AsyncStream.from(source)` static methods are the recommended
+entry points for converting external async types to Groovy's native abstractions. They delegate
+to the `AwaitableAdapterRegistry` internally but provide a more discoverable, user-friendly API:
+
+[source,groovy]
+----
+include::../test/AsyncAwaitSpecTest.groovy[tags=from_conversion,indent=0]
+----
+
+`Awaitable.from()` accepts any type supported by a registered adapter: `CompletableFuture`,
+`CompletionStage`, `Future`, `Flow.Publisher`, or any third-party type with a custom adapter.
+If the source is already an `Awaitable`, it is returned as-is. `AsyncStream.from()` works
+similarly for multi-value sources such as `Iterable`, `Iterator`, or `Flow.Publisher`.
+
+=== Built-in Adapters
+
 The `groovy.concurrent.AwaitableAdapterRegistry` allows extending `await` to support additional
 asynchronous types from third-party frameworks. The built-in adapter handles:
 
@@ -1131,7 +1149,8 @@ JavaScript, C#, Kotlin, and Swift, for developers familiar with those languages.
 | task priority / executor chosen by runtime
 
 | **Third-party support**
-| `AwaitableAdapterRegistry` SPI
+| `AwaitableAdapterRegistry` SPI +
+`Awaitable.from()` / `AsyncStream.from()`
 | _(native `thenable` protocol)_
 | Custom awaiters via `GetAwaiter()`
 | coroutine adapters / bridges
@@ -1195,6 +1214,9 @@ JavaScript, C#, Kotlin, and Swift, for developers familiar with those languages.
 | Pre-computed result
 | `Awaitable.of(value)` / `Awaitable.failed(error)`
 
+| Type conversion
+| `Awaitable.from(source)` / `AsyncStream.from(source)`
+
 | Annotation form
 | `@Async def methodName() { ... }`
 

src/spec/test/AsyncAwaitSpecTest.groovy

@@ -1205,7 +1205,43 @@ assert task.isDone()
     }
 
     // =========================================================================
-    // 19. Custom adapter registration
+    // 19. Type conversion with from()
+    // =========================================================================
+
+    @Test
+    void testFromConversion() {
+        assertScript '''
+// tag::from_conversion[]
+import groovy.concurrent.Awaitable
+import groovy.concurrent.AsyncStream
+import java.util.concurrent.CompletableFuture
+
+// Convert a CompletableFuture to Awaitable
+def cf = CompletableFuture.completedFuture("hello")
+Awaitable<String> awaitable = Awaitable.from(cf)
+assert awaitable.get() == "hello"
+
+// If the source is already an Awaitable, it is returned as-is
+def original = Awaitable.of(42)
+assert Awaitable.from(original).is(original)
+
+// Convert an Iterable to AsyncStream
+AsyncStream<String> stream = AsyncStream.from(["a", "b", "c"])
+def items = []
+assert stream.moveNext().get() == true
+items << stream.current
+assert stream.moveNext().get() == true
+items << stream.current
+assert stream.moveNext().get() == true
+items << stream.current
+assert stream.moveNext().get() == false
+assert items == ["a", "b", "c"]
+// end::from_conversion[]
+        '''
+    }
+
+    // =========================================================================
+    // 20. Custom adapter registration
     // =========================================================================
 
     @Test