├── .gitignore
├── README.md
├── pom.xml
└── src
    ├── main
        └── java
        │   └── com
        │       └── augustnagro
        │           └── jaa
        │               ├── Async.java
        │               └── Coroutine.java
    └── test
        └── java
            └── UnitTests.java


/.gitignore:
--------------------------------------------------------------------------------
 1 | .settings
 2 | .DS_Store
 3 | 
 4 | *.iml
 5 | .idea
 6 | target
 7 | nbproject
 8 | nb-configuration.xml
 9 | 
10 | .class
11 | .log
12 | .jar
13 | .war
14 | .ear
15 | .zip
16 | .tar.gz
17 | .rar
18 | 
19 | hs_err_pid*
20 | 
21 | *.log
22 | 
23 | .bsp
24 | .metals
25 | .bloop
26 | .vscode
27 | metals.sbt
28 | 
29 | *.sc
30 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
 1 | ## Java Async-Await
 2 | 
 3 | Async-Await support for Java [CompletionStage](https://download.java.net/java/early_access/loom/docs/api/java.base/java/util/concurrent/CompletionStage.html).
 4 | 
 5 | ```java
 6 | import com.augustnagro.jaa.AsyncContext;
 7 | import static com.augustnagro.jaa.Async.async;
 8 | import static com.augustnagro.jaa.Async.await;
 9 | 
10 | CompletableFuture<byte[]> pdfForUsers = async(() -> {
11 |   List<Long> userIds = await(userIdsFromDb());
12 | 
13 |   List<String> userNames = userIds.stream()
14 |     .map(id -> await(userNamesFromSomeApi(id)))
15 |     .toList();
16 | 
17 |   byte[] pdf = await(buildPdf(userNames));  //buildPdf returns CompletableFuture<byte[]>
18 |   
19 |   System.out.println("Generated pdf for user ids: " + userIds);
20 |   return pdf;
21 | });
22 | ```
23 | 
24 | vs.
25 | 
26 | ```java
27 | CompletionStage<byte[]> userPdf = userIdsFromDb().thenCompose(userIds -> {
28 | 
29 |   CompletionStage<List<String>> userNamesFuture =
30 |     CompletableFuture.supplyAsync(ArrayList::new);
31 | 
32 |   for (Long userId : userIds) {
33 |     userNamesFuture = userNamesFuture.thenCompose(list -> {
34 |       return userNamesFromSomeApi(userId)
35 |         .thenApply(userName -> {
36 |           list.add(userName);
37 |           return list;
38 |         });
39 |     });
40 |   }
41 | 
42 |   return userNamesFuture.thenCompose(userNames -> {
43 |     return buildPdf(userNames).thenApply(pdf -> {
44 |       System.out.println("Generated pdf for user ids: " + userIds);
45 |       return pdf;
46 |     });
47 |   });
48 | });
49 | ```
50 | 
51 | ## Maven Coordinates
52 | 
53 | ```xml
54 | <dependency>
55 |   <groupId>com.augustnagro</groupId>
56 |   <artifactId>java-async-await</artifactId>
57 |   <version>0.3.0</version>
58 | </dependency>
59 | ```
60 | 
61 | This library requires [JDK 20](https://jdk.java.net/20/) with `--enable-preview`, and has no dependencies.
62 | 
63 | ## Docs:
64 | 
65 | Within an `async` scope, you can `await` CompletionStages and program in an imperative style. Most Future apis implement CompletionStage, or provide conversions. `async` and `await` calls can be nested to any depth.
66 | 
67 | ## Why Async-Await vs the higher-order Future API?
68 | 
69 | Abstractions like Future, Rx, ZIO, Uni, etc, are great. They provide convenient functions, like handling timeout and retries.
70 | 
71 | However, there are serious downsides to implementing business logic in a fully 'monadic' style:
72 | 
73 | * Often it's difficult to express something with Futures, when it is trivial with simple blocking code. 
74 | * `flatMap` and its aliases like `thenCompose` are generally not stack-safe, and will StackOverflow if you recurse far enough (see unit tests for example).
75 | * It's hard to debug big Future chains in IDEs
76 | * Stack traces are often meaningless.
77 | * Future is 'viral', infecting your codebase.
78 | 
79 | Project Loom solves all five issues, although Async-Await only solves the first 3. Stack traces are significantly better then using higher-order functions, but can still lack detail in certain cases. Since `async` returns `CompletableFuture`, it retains the virility of Future-like apis.
80 | 
81 | ## Why Async-Await vs synchronous APIs on Virtual Threads and dropping async entirely?
82 | 
83 | * That's not a bad idea.
84 | * You lose the concurrency features like timeout and retry offered by Rx, Uni, ZIO, etc.
85 | * Maybe you're already using Async libraries; the effort to migrate back to sync is gigantic, whereas introducing Async-Await can be done incrementally.
86 | 
87 | ## Alternative Approaches
88 | 
89 | * Java bytecode manipulation: https://github.com/electronicarts/ea-async
90 | * Scala 3 Async-Await macro: https://github.com/rssh/dotty-cps-async
91 | * Scala 3 Monadic Reflection using Loom: https://github.com/lampepfl/monadic-reflection
92 | * Kotlin Coroutines (another form of bytecode manipulation)
93 | 


--------------------------------------------------------------------------------
/pom.xml:
--------------------------------------------------------------------------------
  1 | <?xml version="1.0" encoding="UTF-8"?>
  2 | <project xmlns="http://maven.apache.org/POM/4.0.0"
  3 |          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  4 |          xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  5 |   <modelVersion>4.0.0</modelVersion>
  6 | 
  7 |   <groupId>com.augustnagro</groupId>
  8 |   <artifactId>java-async-await</artifactId>
  9 |   <version>0.3.1-SNAPSHOT</version>
 10 | 
 11 |   <name>Java Async-Await</name>
 12 |   <description>Async-Await support for Java</description>
 13 |   <url>https://github.com/AugustNagro/java-async-await</url>
 14 | 
 15 |   <properties>
 16 |     <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
 17 |     <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
 18 |   </properties>
 19 | 
 20 |   <developers>
 21 |     <developer>
 22 |       <id>augustnagro@gmail.com</id>
 23 |       <name>August Nagro</name>
 24 |       <email>augustnagro@gmail.com</email>
 25 |       <url>https://augustnagro.com</url>
 26 |     </developer>
 27 |   </developers>
 28 | 
 29 |   <licenses>
 30 |     <license>
 31 |       <name>Apache License, Version 2.0</name>
 32 |       <url>http://www.apache.org/licenses/LICENSE-2.0.txt</url>
 33 |       <distribution>repo</distribution>
 34 |     </license>
 35 |   </licenses>
 36 | 
 37 |   <scm>
 38 |     <url>https://github.com/AugustNagro/java-async-await</url>
 39 |     <connection>scm:git:git@github.com:augustnagro/java-async-await.git</connection>
 40 |     <developerConnection>scm:git:git@github.com:augustnagro/java-async-await.git</developerConnection>
 41 |   </scm>
 42 | 
 43 |   <distributionManagement>
 44 |     <snapshotRepository>
 45 |       <id>ossrh</id>
 46 |       <url>https://oss.sonatype.org/content/repositories/snapshots</url>
 47 |     </snapshotRepository>
 48 |     <repository>
 49 |       <id>ossrh</id>
 50 |       <url>https://oss.sonatype.org/service/local/staging/deploy/maven2</url>
 51 |     </repository>
 52 |   </distributionManagement>
 53 | 
 54 |   <dependencies>
 55 |     <dependency>
 56 |       <groupId>junit</groupId>
 57 |       <artifactId>junit</artifactId>
 58 |       <version>4.13.2</version>
 59 |       <scope>test</scope>
 60 |     </dependency>
 61 |   </dependencies>
 62 | 
 63 |   <build>
 64 |     <plugins>
 65 |       <plugin>
 66 |         <groupId>org.apache.maven.plugins</groupId>
 67 |         <artifactId>maven-compiler-plugin</artifactId>
 68 |         <version>3.8.1</version>
 69 |         <configuration>
 70 |           <release>20</release>
 71 |           <compilerArgs>
 72 |             <compilerArg>--enable-preview</compilerArg>
 73 |           </compilerArgs>
 74 |         </configuration>
 75 |       </plugin>
 76 | 
 77 |       <plugin>
 78 |         <groupId>org.apache.maven.plugins</groupId>
 79 |         <artifactId>maven-surefire-plugin</artifactId>
 80 |         <version>2.22.2</version>
 81 |         <configuration>
 82 |           <argLine>--enable-preview</argLine>
 83 |         </configuration>
 84 |       </plugin>
 85 | 
 86 |       <plugin>
 87 |         <groupId>org.apache.maven.plugins</groupId>
 88 |         <artifactId>maven-deploy-plugin</artifactId>
 89 |         <version>2.8.2</version>
 90 |       </plugin>
 91 | 
 92 |       <plugin>
 93 |         <groupId>org.apache.maven.plugins</groupId>
 94 |         <artifactId>maven-source-plugin</artifactId>
 95 |         <version>3.2.0</version>
 96 |         <executions>
 97 |           <execution>
 98 |             <id>attach-sources</id>
 99 |             <goals>
100 |               <goal>jar-no-fork</goal>
101 |             </goals>
102 |           </execution>
103 |         </executions>
104 |       </plugin>
105 | 
106 |       <plugin>
107 |         <groupId>org.apache.maven.plugins</groupId>
108 |         <artifactId>maven-javadoc-plugin</artifactId>
109 |         <version>3.3.0</version>
110 |         <executions>
111 |           <execution>
112 |             <id>attach-javadocs</id>
113 |             <goals>
114 |               <goal>jar</goal>
115 |             </goals>
116 |           </execution>
117 |         </executions>
118 |       </plugin>
119 | 
120 |       <plugin>
121 |         <groupId>org.apache.maven.plugins</groupId>
122 |         <artifactId>maven-gpg-plugin</artifactId>
123 |         <version>3.0.1</version>
124 |         <executions>
125 |           <execution>
126 |             <id>sign-artifacts</id>
127 |             <phase>verify</phase>
128 |             <goals>
129 |               <goal>sign</goal>
130 |             </goals>
131 |           </execution>
132 |         </executions>
133 |       </plugin>
134 |     </plugins>
135 |   </build>
136 | 
137 | </project>
138 | 


--------------------------------------------------------------------------------
/src/main/java/com/augustnagro/jaa/Async.java:
--------------------------------------------------------------------------------
 1 | package com.augustnagro.jaa;
 2 | 
 3 | import java.util.Objects;
 4 | import java.util.concurrent.Callable;
 5 | import java.util.concurrent.CompletableFuture;
 6 | import java.util.concurrent.CompletionStage;
 7 | 
 8 | public class Async {
 9 | 
10 |   // todo refactor to use ScopeLocal when it's no longer a draft JEP.
11 |   // https://openjdk.java.net/jeps/8263012
12 |   private static final ThreadLocal<Coroutine> AWAIT_CONTEXT = new ThreadLocal<>();
13 | 
14 |   public static <A> CompletableFuture<A> async(Callable<A> fn) {
15 |     CompletableFuture<A> promise = new CompletableFuture<>();
16 |     Thread.startVirtualThread(() -> {
17 |       try {
18 |         AWAIT_CONTEXT.set(new Coroutine());
19 |         promise.complete(fn.call());
20 |       } catch (Throwable t) {
21 |         promise.completeExceptionally(t);
22 |       } finally {
23 |         AWAIT_CONTEXT.remove();
24 |       }
25 |     });
26 |     return promise;
27 |   }
28 | 
29 |   public static <A> A await(CompletionStage<A> stage) {
30 |     Coroutine coroutine = Objects.requireNonNull(
31 |       AWAIT_CONTEXT.get(),
32 |       "await must be called within an async block"
33 |     );
34 | 
35 |     return coroutine.await(stage);
36 |   }
37 | }
38 | 


--------------------------------------------------------------------------------
/src/main/java/com/augustnagro/jaa/Coroutine.java:
--------------------------------------------------------------------------------
 1 | package com.augustnagro.jaa;
 2 | 
 3 | import java.util.concurrent.CompletionStage;
 4 | import java.util.concurrent.locks.Condition;
 5 | import java.util.concurrent.locks.ReentrantLock;
 6 | 
 7 | /**
 8 |  * Must be run in a Virtual Thread, so that blocking until the
 9 |  * CompletionStage completes does not degrade performance.
10 |  */
11 | class Coroutine {
12 | 
13 |   private final ReentrantLock lock = new ReentrantLock();
14 |   private final Condition cond = lock.newCondition();
15 | 
16 |   public <A> A await(CompletionStage<A> stage) {
17 |     lock.lock();
18 |     try {
19 | 
20 |       stage.whenCompleteAsync((A res, Throwable ex) -> {
21 |         lock.lock();
22 |         try {
23 |           cond.signal();
24 |         } finally {
25 |           lock.unlock();
26 |         }
27 |       });
28 | 
29 |       cond.await();
30 | 
31 |       return stage.toCompletableFuture().join();
32 | 
33 |     } catch (InterruptedException e) {
34 |       throw new RuntimeException(e);
35 | 
36 |     } finally {
37 |       lock.unlock();
38 |     }
39 |   }
40 | }
41 | 


--------------------------------------------------------------------------------
/src/test/java/UnitTests.java:
--------------------------------------------------------------------------------
  1 | import org.junit.Ignore;
  2 | import org.junit.Test;
  3 | 
  4 | import java.util.ArrayList;
  5 | import java.util.List;
  6 | import java.util.concurrent.CompletableFuture;
  7 | import java.util.concurrent.CompletionStage;
  8 | import java.util.concurrent.ExecutionException;
  9 | import java.util.concurrent.Future;
 10 | 
 11 | import static com.augustnagro.jaa.Async.async;
 12 | import static com.augustnagro.jaa.Async.await;
 13 | import static org.junit.Assert.assertEquals;
 14 | 
 15 | public class UnitTests {
 16 | 
 17 |   CompletionStage<List<Long>> userIdsFromDb() {
 18 |     return CompletableFuture.completedFuture(List.of(1L, 2L, 3L));
 19 |   }
 20 | 
 21 |   CompletionStage<String> userNamesFromSomeApi(Long userId) {
 22 |     return CompletableFuture.supplyAsync(() -> "User " + userId);
 23 |   }
 24 | 
 25 |   CompletionStage<byte[]> buildPdf(List<String> userNames) {
 26 |     return CompletableFuture.completedFuture(new byte[0]);
 27 |   }
 28 | 
 29 |   @Test
 30 |   public void testSimpleAsyncAwait() {
 31 |     CompletableFuture<byte[]> future = async(() -> {
 32 |       List<Long> userIds = await(userIdsFromDb());
 33 | 
 34 |       List<String> userNames = userIds.stream()
 35 |         .map(id -> await(userNamesFromSomeApi(id)))
 36 |         .toList();
 37 | 
 38 |       byte[] pdf = await(buildPdf(userNames));
 39 | 
 40 |       System.out.println("Generated pdf for user ids: " + userIds);
 41 |       return pdf;
 42 |     });
 43 | 
 44 |     assertEquals(0, future.join().length);
 45 |   }
 46 | 
 47 |   @Test
 48 |   public void testSimple() {
 49 |     CompletionStage<byte[]> userPdf = userIdsFromDb().thenCompose(userIds -> {
 50 | 
 51 |       CompletionStage<List<String>> userNamesFuture =
 52 |         CompletableFuture.supplyAsync(ArrayList::new);
 53 | 
 54 |       for (Long userId : userIds) {
 55 |         userNamesFuture = userNamesFuture.thenCompose(list -> {
 56 |           return userNamesFromSomeApi(userId)
 57 |             .thenApply(userName -> {
 58 |               list.add(userName);
 59 |               return list;
 60 |             });
 61 |         });
 62 |       }
 63 | 
 64 |       return userNamesFuture.thenCompose(userNames -> {
 65 |         return buildPdf(userNames).thenApply(pdf -> {
 66 |           System.out.println("Generated pdf for user ids: " + userIds);
 67 |           return pdf;
 68 |         });
 69 |       });
 70 |     });
 71 | 
 72 |     assertEquals(0, userPdf.toCompletableFuture().join().length);
 73 |   }
 74 | 
 75 | 
 76 |   @Test
 77 |   public void testAwaitNesting() throws ExecutionException, InterruptedException {
 78 |     Future<Integer> future = async(() -> {
 79 |       List<Long> ids1 = await(userIdsFromDb());
 80 |       List<Long> ids2 = await(async(() -> await(userIdsFromDb())));
 81 | 
 82 |       return ids1.size() + ids2.size();
 83 |     });
 84 | 
 85 |     assertEquals(6L, future.get().longValue());
 86 |   }
 87 | 
 88 |   @Test
 89 |   public void testAwaitForLoop() throws ExecutionException, InterruptedException {
 90 |     Future<String> future = async(() -> {
 91 |       ArrayList<String> userNames = new ArrayList<>();
 92 |       for (long userId = 1; userId <= 1000; ++userId) {
 93 |         userNames.add(await(userNamesFromSomeApi(userId)));
 94 |       }
 95 | 
 96 |       return userNames.get(userNames.size() - 1);
 97 |     });
 98 | 
 99 |     assertEquals("User 1000", future.get());
100 |   }
101 | 
102 |   private static final long RECURSE_ITERATIONS = 20_000;
103 | 
104 |   @Test
105 |   public void testRecursiveAwait() {
106 |     CompletableFuture<Long> future = recurseAsync(RECURSE_ITERATIONS, 0);
107 | 
108 |     assertEquals(RECURSE_ITERATIONS, future.join().longValue());
109 |   }
110 | 
111 |   private CompletableFuture<Long> recurseAsync(long iterations, long result) {
112 |     return async(() -> {
113 |       if (iterations == 0) {
114 |         return result;
115 |       } else {
116 |         Long newResult = await(calculateNewResult(result));
117 |         return await(recurseAsync(iterations - 1, newResult));
118 |       }
119 |     });
120 |   }
121 | 
122 |   private CompletionStage<Long> calculateNewResult(long oldResult) {
123 |     return CompletableFuture.completedFuture(oldResult + 1);
124 |   }
125 | 
126 | 
127 |   @Test
128 |   @Ignore
129 |   public void testRecursiveFlatMap() {
130 |     CompletionStage<Long> future = recurseFlatMap(RECURSE_ITERATIONS, 0);
131 |     assertEquals(RECURSE_ITERATIONS, future.toCompletableFuture().join().longValue());
132 |   }
133 | 
134 |   private CompletionStage<Long> recurseFlatMap(long iterations, long result) {
135 |     CompletionStage<Long> newResult = calculateNewResult(result);
136 |     return newResult.thenCompose(nr -> recurseFlatMap(iterations - 1, nr));
137 |   }
138 | 
139 | 
140 | }
141 | 


--------------------------------------------------------------------------------