completablefuture: CompletableFuture module (thenApply vs thenCompose and the serial trap, which thread runs a stage incl. join() running dependents, CompletionException wrapping, orTimeout/cancel not stopping work, allOf/anyOf with fail-fast and first-success helpers, virtual-thread timings, StructuredTaskScope preview error), 26 contract tests
Co-Authored-By: Claude Sonnet 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_017ic4b3dRuKRhrHFPzWSSxr
This commit is contained in:
co-authored by
Claude Sonnet 5.5
parent
59a5435825
commit
9c2ae10d7f
@@ -0,0 +1,76 @@
|
||||
# completablefuture
|
||||
|
||||
Companion code for the ankurm.com post *"CompletableFuture in Java: thenApply vs thenCompose, allOf,
|
||||
Exceptions and Timeouts (and When Virtual Threads Win)"* — https://ankurm.com/java-completablefuture-thenapply-thencompose-allof-timeouts/ . Thirty-first
|
||||
module in `java-core-examples`, the Java-core / concurrency series.
|
||||
|
||||
The post is the only documentation: every explanation, diagram and deeper-dive section lives there,
|
||||
and each code block in it links to a file in this module. There is deliberately no `docs/` folder.
|
||||
|
||||
Seven demos, each isolating one thing people get wrong about `CompletableFuture`: `thenApply` vs
|
||||
`thenCompose` (and the serial-by-accident trap), which thread runs each stage, the way `join()`
|
||||
can run your stage on the waiting thread, what `exceptionally` / `handle` / `whenComplete` actually
|
||||
receive, why `orTimeout` and `cancel(true)` do not stop the work, how `allOf` / `anyOf` behave when
|
||||
something fails, and a measured comparison against virtual threads.
|
||||
|
||||
## Versions this was built and tested against
|
||||
|
||||
| Component | Version | Notes |
|
||||
|---|---|---|
|
||||
| JDK | 25.0.5.1+2 (Temurin, LTS) | Every demo runs on one JDK. |
|
||||
| JUnit Jupiter | 6.1.3 | Latest GA on Maven Central at the time of writing. |
|
||||
| maven-surefire-plugin | 3.6.1 | |
|
||||
| maven-compiler-plugin | 3.16.0 | `<release>25</release>` |
|
||||
| Maven | 3.9.11 | |
|
||||
| Hardware | 2 vCPU x86-64 VM | So the common pool has parallelism 1 — see the notes below. |
|
||||
|
||||
## Quickstart
|
||||
|
||||
```bash
|
||||
export JAVA_HOME=/path/to/jdk-25
|
||||
mvn package
|
||||
java -cp target/classes com.ankurm.completablefuture.ThenApplyVsComposeDemo
|
||||
java -cp target/classes com.ankurm.completablefuture.VirtualThreadsBenchmark
|
||||
```
|
||||
|
||||
`scripts/run-all.sh` regenerates every file in `output/` (needs a JDK 25 on `PATH`).
|
||||
|
||||
## What's in here
|
||||
|
||||
| File | What it shows |
|
||||
|---|---|
|
||||
| `.../ThenApplyVsComposeDemo.java` | `thenApply` with a future-returning function nests the future; `thenCompose` flattens it; independent calls chained with `thenCompose` run serially (221 ms vs 125 ms with `thenCombine`). |
|
||||
| `.../WhichThreadDemo.java` | A stage runs on the completing thread if registered before completion, and on the caller if registered after. `...Async` moves it to the async pool or your executor. |
|
||||
| `.../JoinHelpsDemo.java` | A thread blocked in `join()` on the source future can run the dependent stage itself. Waiting on a `CountDownLatch` instead never does. |
|
||||
| `.../ExceptionHandlingDemo.java` | The `CompletionException` wrapper: when `exceptionally` sees it raw and when wrapped; `join()` vs `get()`; `handle` vs `whenComplete`; `exceptionallyCompose`. |
|
||||
| `.../TimeoutDemo.java` | `orTimeout` / `completeOnTimeout` complete the future, not the task. `cancel(true)` does not interrupt. The fix: cancel the executor's own `Future`. |
|
||||
| `.../AllOfAnyOfDemo.java` | `allOf` is `Void` and waits for the slowest even after a failure; `allOrFailFast` and `firstSuccess` helpers; `anyOf` counts a failure as a win. |
|
||||
| `.../VirtualThreadsBenchmark.java` | 300 blocking tasks and 16 CPU-bound tasks across the default pool, fixed pools and a virtual-thread executor. |
|
||||
| `src/broken/StructuredScopeWithoutPreview.java` | Not compiled by Maven. `scripts/compile-broken.sh` captures javac's message: `StructuredTaskScope` is a preview API on JDK 25. |
|
||||
| `src/test/.../CompletableFutureContractTest.java` | 26 tests pinning every deterministic behaviour the post states. Timing assertions check shape, not exact milliseconds. |
|
||||
| `output/01`-`07` | Each demo's real run. |
|
||||
| `output/08` | The compiler message for the preview-API failure. |
|
||||
| `output/09` | JUnit summary. |
|
||||
|
||||
## Reading the results honestly (2-vCPU sandbox)
|
||||
|
||||
**The default-pool row in `output/07` is a sandbox artefact, and also a real warning.** With 2
|
||||
cores the common pool's parallelism is 1 (the default is `max(1, cores - 1)`), so 300 tasks sleeping
|
||||
50 ms took 15,095 ms: 300 x 50 ms, one after another. On an 8-core machine the same code would have
|
||||
7 workers and take roughly a seventh of that. The lesson survives the hardware: the common pool is
|
||||
sized for CPU work, and a blocking task occupies a worker for its whole sleep.
|
||||
|
||||
**Virtual threads do not make CPU-bound work faster.** In the CPU-bound block a fixed pool of 2
|
||||
threads (= cores) took 1,185 ms and a virtual-thread executor 1,116 ms. Both are bounded by 2
|
||||
cores; treat that gap as noise, not a result: it flipped sign between earlier runs.
|
||||
|
||||
**`output/03` varies from run to run, on purpose.** How often `join()` runs the stage on the
|
||||
waiting thread depends on a race between that thread and the worker. Across the runs made while
|
||||
writing the post the count ranged from 8 to 104 of 200 (37 in the committed run); the latch loop was 0 every time.
|
||||
|
||||
**Timing figures drift between runs.** Everything except the ordering of the rows (virtual < fixed
|
||||
200 < fixed 50 << default pool for blocking work) should be read as indicative.
|
||||
|
||||
## License
|
||||
|
||||
MIT - see the [repo-wide LICENSE](../LICENSE).
|
||||
@@ -0,0 +1,11 @@
|
||||
== 1. thenApply with a function that itself returns a CompletableFuture
|
||||
nested.join() is a: CompletableFuture
|
||||
inner.join() is: Order[userId=1, item=laptop]
|
||||
|
||||
== 2. thenCompose flattens it
|
||||
flat.join() is: Order[userId=1, item=laptop]
|
||||
|
||||
== 3. Same three tools, measured (fixed pool of 4, so nothing queues)
|
||||
dependent calls: thenCompose (100 ms then 150 ms) -> Order[userId=1, item=laptop] 251 ms
|
||||
independent calls: start both, then thenCombine -> ankur + winter-sale 125 ms
|
||||
independent calls, wrongly chained with thenCompose -> ankur + winter-sale 221 ms
|
||||
@@ -0,0 +1,17 @@
|
||||
availableProcessors = 2
|
||||
common pool parallelism = 1
|
||||
caller thread = main
|
||||
|
||||
== Stage registered WHILE the previous stage is still running
|
||||
supplyAsync body ran on ForkJoinPool.commonPool-worker-1
|
||||
thenApply (registered before slow finished) ran on ForkJoinPool.commonPool-worker-1
|
||||
thenApplyAsync (no executor) ran on ForkJoinPool.commonPool-worker-1
|
||||
thenApplyAsync (executor = mine) ran on my-pool-1
|
||||
|
||||
== Stage registered AFTER the previous stage finished
|
||||
thenApply (registered after slow finished) ran on main
|
||||
thenApply on completedFuture(..) ran on main
|
||||
|
||||
== Supplying with your own executor
|
||||
supplyAsync(.., mine) body ran on my-pool-2
|
||||
thenApply after supplyAsync(.., mine) ran on my-pool-2
|
||||
@@ -0,0 +1,11 @@
|
||||
trials per loop: 200
|
||||
stage ran on main when main waited with join(): 37
|
||||
stage ran on main when main waited on a CountDownLatch: 0
|
||||
|
||||
stack of the first stage that ran on main while it was inside join():
|
||||
at com.ankurm.completablefuture.JoinHelpsDemo.lambda$main$1(JoinHelpsDemo.java:35)
|
||||
at java.base/java.util.concurrent.CompletableFuture$UniAccept.tryFire(CompletableFuture.java:739)
|
||||
at java.base/java.util.concurrent.CompletableFuture.postComplete(CompletableFuture.java:531)
|
||||
at java.base/java.util.concurrent.CompletableFuture.waitingGet(CompletableFuture.java:1930)
|
||||
at java.base/java.util.concurrent.CompletableFuture.join(CompletableFuture.java:2138)
|
||||
at com.ankurm.completablefuture.JoinHelpsDemo.main(JoinHelpsDemo.java:39)
|
||||
@@ -0,0 +1,23 @@
|
||||
== 1. What does exceptionally() receive?
|
||||
supplyAsync threw, exceptionally on same stage: CompletionException <- cause IllegalStateException: boom
|
||||
completeExceptionally(raw), same stage: IllegalStateException: boom
|
||||
completeExceptionally(raw), one stage later: CompletionException <- cause IllegalStateException: boom
|
||||
|
||||
== 2. What do join() and get() throw?
|
||||
join(): CompletionException <- cause IllegalStateException: boom
|
||||
get(): ExecutionException <- cause IllegalStateException: boom
|
||||
state() = FAILED, exceptionNow() = IllegalStateException: boom
|
||||
|
||||
== 3. exceptionally vs handle vs whenComplete
|
||||
exceptionally(ex -> -1) -> -1
|
||||
handle((v, ex) -> ex==null?v:-2) -> -2
|
||||
whenComplete saw: CompletionException <- cause IllegalStateException: boom
|
||||
whenComplete did not recover; join(): CompletionException <- cause IllegalStateException: boom
|
||||
|
||||
== 4. On success, each one is a pass-through or a transformer
|
||||
exceptionally on success: 7
|
||||
handle on success: 14
|
||||
whenComplete on success: 7
|
||||
|
||||
== 5. exceptionallyCompose: recover with another async call (JDK 12+)
|
||||
recovered value: 99
|
||||
@@ -0,0 +1,17 @@
|
||||
== 1. orTimeout: the future fails, the task keeps running
|
||||
join() after 100 ms: CompletionException <- cause TimeoutException: null
|
||||
task finished right after that? false
|
||||
task finished 700 ms later? true
|
||||
|
||||
== 2. completeOnTimeout: a fallback value instead of an exception
|
||||
join() returned: fallback value
|
||||
|
||||
== 3. cancel(true) does not interrupt the task either
|
||||
cancel(true) returned: true
|
||||
join(): CancellationException
|
||||
task saw an interrupt? false
|
||||
task ran to the end anyway? true
|
||||
|
||||
== 4. The fix: keep the executor's Future and cancel THAT on timeout
|
||||
join(): CompletionException <- cause TimeoutException: null
|
||||
task saw an interrupt? true
|
||||
@@ -0,0 +1,19 @@
|
||||
== 1. allOf returns CompletableFuture<Void> - you collect results yourself
|
||||
collected: [a, b, c]
|
||||
|
||||
== 2. allOf with one early failure: it waits for the slow one anyway
|
||||
allOf failed with: CompletionException <- cause IllegalStateException: failed after 50 ms
|
||||
after 401 ms (the failure itself happened at 50 ms)
|
||||
slow task finished by then? true
|
||||
|
||||
== 3. allOrFailFast: fail at the first failure, but nothing is cancelled
|
||||
failed with: CompletionException <- cause IllegalStateException: failed after 50 ms
|
||||
after 50 ms
|
||||
slow task finished by then? false
|
||||
slow task finished 450 ms later? true
|
||||
|
||||
== 4. anyOf returns the first COMPLETION, and a failure counts
|
||||
anyOf failed with: CompletionException <- cause IllegalStateException: failed after 30 ms
|
||||
|
||||
== 5. firstSuccess: skip failures, take the first value
|
||||
firstSuccess result: slow ok
|
||||
@@ -0,0 +1,14 @@
|
||||
availableProcessors = 2
|
||||
common pool parallelism = 1
|
||||
|
||||
== Blocking work: 300 tasks, each sleeping 50 ms (a stand-in for a remote call)
|
||||
default async pool (no executor argument) 15095 ms
|
||||
fixed pool, 50 threads 309 ms
|
||||
fixed pool, 200 threads 117 ms
|
||||
virtual thread per task 62 ms
|
||||
|
||||
== CPU-bound work: 16 tasks, each 2,000,000 rounds of SHA-256
|
||||
sequential, one thread (baseline) 2237 ms
|
||||
default async pool (no executor argument) 2159 ms
|
||||
fixed pool, 2 threads (= cores) 1185 ms
|
||||
virtual thread per task 1116 ms
|
||||
@@ -0,0 +1,9 @@
|
||||
src/broken/StructuredScopeWithoutPreview.java:1: error: StructuredTaskScope is a preview API and is disabled by default.
|
||||
import java.util.concurrent.StructuredTaskScope;
|
||||
^
|
||||
(use --enable-preview to enable preview APIs)
|
||||
src/broken/StructuredScopeWithoutPreview.java:11: error: StructuredTaskScope is a preview API and is disabled by default.
|
||||
try (var scope = StructuredTaskScope.open()) {
|
||||
^
|
||||
(use --enable-preview to enable preview APIs)
|
||||
2 errors
|
||||
@@ -0,0 +1,3 @@
|
||||
[INFO] Tests run: 26, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 2.421 s -- in com.ankurm.completablefuture.CompletableFutureContractTest
|
||||
[INFO] Tests run: 26, Failures: 0, Errors: 0, Skipped: 0
|
||||
[INFO] BUILD SUCCESS
|
||||
@@ -0,0 +1,43 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<project xmlns="http://maven.apache.org/POM/4.0.0"
|
||||
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
|
||||
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
|
||||
<modelVersion>4.0.0</modelVersion>
|
||||
|
||||
<parent>
|
||||
<groupId>com.ankurm</groupId>
|
||||
<artifactId>java-core-examples</artifactId>
|
||||
<version>1.0</version>
|
||||
</parent>
|
||||
|
||||
<artifactId>completablefuture</artifactId>
|
||||
<name>completablefuture</name>
|
||||
<description>CompletableFuture in Java: thenApply vs thenCompose, which thread runs each stage, exception handling (exceptionally/handle/whenComplete), orTimeout/completeOnTimeout, allOf/anyOf, and a measured comparison with virtual threads.</description>
|
||||
|
||||
<dependencies>
|
||||
<dependency>
|
||||
<groupId>org.junit.jupiter</groupId>
|
||||
<artifactId>junit-jupiter</artifactId>
|
||||
<version>6.1.3</version>
|
||||
<scope>test</scope>
|
||||
</dependency>
|
||||
</dependencies>
|
||||
|
||||
<build>
|
||||
<plugins>
|
||||
<plugin>
|
||||
<groupId>org.apache.maven.plugins</groupId>
|
||||
<artifactId>maven-compiler-plugin</artifactId>
|
||||
<version>3.16.0</version>
|
||||
<configuration>
|
||||
<release>25</release>
|
||||
</configuration>
|
||||
</plugin>
|
||||
<plugin>
|
||||
<groupId>org.apache.maven.plugins</groupId>
|
||||
<artifactId>maven-surefire-plugin</artifactId>
|
||||
<version>3.6.1</version>
|
||||
</plugin>
|
||||
</plugins>
|
||||
</build>
|
||||
</project>
|
||||
Executable
+8
@@ -0,0 +1,8 @@
|
||||
#!/usr/bin/env bash
|
||||
# Captures the compiler's own message for src/broken/StructuredScopeWithoutPreview.java.
|
||||
set -uo pipefail
|
||||
cd "$(dirname "$0")/.."
|
||||
mkdir -p output target/broken
|
||||
javac -d target/broken src/broken/StructuredScopeWithoutPreview.java 2>&1 \
|
||||
| grep -v -e '^Picked up JAVA_TOOL_OPTIONS' -e '^Picked up _JAVA_OPTIONS' > output/08-structured-scope-without-preview.txt
|
||||
echo "==> 08-structured-scope-without-preview"
|
||||
Executable
+18
@@ -0,0 +1,18 @@
|
||||
#!/usr/bin/env bash
|
||||
# Regenerates every file in output/. Needs a JDK 25 on PATH (or JAVA_HOME set to one).
|
||||
# 03 (join counts) and 07 (timings) drift between runs and depend on core count: indicative only.
|
||||
set -euo pipefail
|
||||
cd "$(dirname "$0")/.."
|
||||
mvn -q -B compile 2>&1 | grep -v -e '^WARNING' -e '^Picked up' || true
|
||||
mkdir -p output
|
||||
run() { java -cp target/classes "com.ankurm.completablefuture.$1" 2>&1 | grep -v -e '^Picked up JAVA_TOOL_OPTIONS' -e '^Picked up _JAVA_OPTIONS' > "output/$2.txt"; echo "==> $2"; }
|
||||
run ThenApplyVsComposeDemo 01-thenapply-vs-thencompose
|
||||
run WhichThreadDemo 02-which-thread
|
||||
run JoinHelpsDemo 03-join-helps
|
||||
run ExceptionHandlingDemo 04-exception-handling
|
||||
run TimeoutDemo 05-timeouts-and-cancel
|
||||
run AllOfAnyOfDemo 06-allof-anyof
|
||||
run VirtualThreadsBenchmark 07-virtual-threads-timings
|
||||
./scripts/compile-broken.sh
|
||||
mvn -B test 2>&1 | grep -E 'Tests run:|BUILD|ERROR|FAIL' | grep -v 'Picked up' > output/09-tests.txt
|
||||
echo "regenerated:"; ls output
|
||||
@@ -0,0 +1,15 @@
|
||||
import java.util.concurrent.StructuredTaskScope;
|
||||
|
||||
/**
|
||||
* Deliberately NOT part of the build (it lives outside src/main). scripts/compile-broken.sh runs
|
||||
* javac on it so the compiler's own message can be committed to output/.
|
||||
*
|
||||
* StructuredTaskScope is a preview API in JDK 25, so this fails without --enable-preview.
|
||||
*/
|
||||
public class StructuredScopeWithoutPreview {
|
||||
public static void main(String[] args) throws Exception {
|
||||
try (var scope = StructuredTaskScope.open()) {
|
||||
scope.join();
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,125 @@
|
||||
package com.ankurm.completablefuture;
|
||||
|
||||
import java.util.List;
|
||||
import java.util.concurrent.CompletableFuture;
|
||||
import java.util.concurrent.CompletionException;
|
||||
import java.util.concurrent.ExecutorService;
|
||||
import java.util.concurrent.Executors;
|
||||
import java.util.concurrent.atomic.AtomicBoolean;
|
||||
import java.util.concurrent.atomic.AtomicInteger;
|
||||
|
||||
import static com.ankurm.completablefuture.Util.describe;
|
||||
import static com.ankurm.completablefuture.Util.sleep;
|
||||
|
||||
/** allOf and anyOf: what they return, when they complete, and the two helpers you end up writing. */
|
||||
public class AllOfAnyOfDemo {
|
||||
|
||||
static CompletableFuture<String> after(long ms, String value, ExecutorService pool) {
|
||||
return CompletableFuture.supplyAsync(() -> {
|
||||
sleep(ms);
|
||||
return value;
|
||||
}, pool);
|
||||
}
|
||||
|
||||
static CompletableFuture<String> failAfter(long ms, ExecutorService pool) {
|
||||
return CompletableFuture.supplyAsync(() -> {
|
||||
sleep(ms);
|
||||
throw new IllegalStateException("failed after " + ms + " ms");
|
||||
}, pool);
|
||||
}
|
||||
|
||||
/** Completes as soon as ANY input fails; completes normally only when ALL succeed. */
|
||||
static CompletableFuture<Void> allOrFailFast(List<? extends CompletableFuture<?>> futures) {
|
||||
CompletableFuture<Void> result = new CompletableFuture<>();
|
||||
futures.forEach(f -> f.whenComplete((v, ex) -> {
|
||||
if (ex != null) {
|
||||
result.completeExceptionally(ex);
|
||||
}
|
||||
}));
|
||||
CompletableFuture.allOf(futures.toArray(CompletableFuture[]::new)).thenRun(() -> result.complete(null));
|
||||
return result;
|
||||
}
|
||||
|
||||
/** Completes with the first SUCCESS; fails only if every input fails. */
|
||||
static <T> CompletableFuture<T> firstSuccess(List<CompletableFuture<T>> futures) {
|
||||
CompletableFuture<T> result = new CompletableFuture<>();
|
||||
AtomicInteger failures = new AtomicInteger();
|
||||
for (CompletableFuture<T> f : futures) {
|
||||
f.whenComplete((v, ex) -> {
|
||||
if (ex == null) {
|
||||
result.complete(v);
|
||||
} else if (failures.incrementAndGet() == futures.size()) {
|
||||
result.completeExceptionally(ex);
|
||||
}
|
||||
});
|
||||
}
|
||||
return result;
|
||||
}
|
||||
|
||||
public static void main(String[] args) {
|
||||
try (ExecutorService pool = Executors.newFixedThreadPool(4)) {
|
||||
|
||||
System.out.println("== 1. allOf returns CompletableFuture<Void> - you collect results yourself");
|
||||
CompletableFuture<String> a = after(50, "a", pool);
|
||||
CompletableFuture<String> b = after(80, "b", pool);
|
||||
CompletableFuture<String> c = after(30, "c", pool);
|
||||
CompletableFuture<List<String>> all = CompletableFuture.allOf(a, b, c)
|
||||
.thenApply(v -> List.of(a.join(), b.join(), c.join()));
|
||||
System.out.println("collected: " + all.join());
|
||||
|
||||
System.out.println();
|
||||
System.out.println("== 2. allOf with one early failure: it waits for the slow one anyway");
|
||||
AtomicBoolean slowDone = new AtomicBoolean();
|
||||
CompletableFuture<String> early = failAfter(50, pool);
|
||||
CompletableFuture<String> slow = CompletableFuture.supplyAsync(() -> {
|
||||
sleep(400);
|
||||
slowDone.set(true);
|
||||
return "slow ok";
|
||||
}, pool);
|
||||
long t0 = System.nanoTime();
|
||||
try {
|
||||
CompletableFuture.allOf(early, slow).join();
|
||||
} catch (CompletionException e) {
|
||||
long ms = (System.nanoTime() - t0) / 1_000_000;
|
||||
System.out.println("allOf failed with: " + describe(e));
|
||||
System.out.println("after " + ms + " ms (the failure itself happened at 50 ms)");
|
||||
System.out.println("slow task finished by then? " + slowDone.get());
|
||||
}
|
||||
|
||||
System.out.println();
|
||||
System.out.println("== 3. allOrFailFast: fail at the first failure, but nothing is cancelled");
|
||||
AtomicBoolean slow2Done = new AtomicBoolean();
|
||||
CompletableFuture<String> early2 = failAfter(50, pool);
|
||||
CompletableFuture<String> slow2 = CompletableFuture.supplyAsync(() -> {
|
||||
sleep(400);
|
||||
slow2Done.set(true);
|
||||
return "slow ok";
|
||||
}, pool);
|
||||
long t1 = System.nanoTime();
|
||||
try {
|
||||
allOrFailFast(List.of(early2, slow2)).join();
|
||||
} catch (CompletionException e) {
|
||||
long ms = (System.nanoTime() - t1) / 1_000_000;
|
||||
System.out.println("failed with: " + describe(e));
|
||||
System.out.println("after " + ms + " ms");
|
||||
System.out.println("slow task finished by then? " + slow2Done.get());
|
||||
}
|
||||
sleep(450);
|
||||
System.out.println("slow task finished 450 ms later? " + slow2Done.get());
|
||||
|
||||
System.out.println();
|
||||
System.out.println("== 4. anyOf returns the first COMPLETION, and a failure counts");
|
||||
CompletableFuture<Object> any = CompletableFuture.anyOf(failAfter(30, pool), after(100, "slow ok", pool));
|
||||
try {
|
||||
System.out.println("anyOf result: " + any.join());
|
||||
} catch (CompletionException e) {
|
||||
System.out.println("anyOf failed with: " + describe(e));
|
||||
}
|
||||
|
||||
System.out.println();
|
||||
System.out.println("== 5. firstSuccess: skip failures, take the first value");
|
||||
String winner = firstSuccess(List.of(failAfter(30, pool), after(100, "slow ok", pool), after(300, "slower", pool))).join();
|
||||
System.out.println("firstSuccess result: " + winner);
|
||||
}
|
||||
}
|
||||
}
|
||||
+95
@@ -0,0 +1,95 @@
|
||||
package com.ankurm.completablefuture;
|
||||
|
||||
import java.util.concurrent.CompletableFuture;
|
||||
import java.util.concurrent.CompletionException;
|
||||
import java.util.concurrent.ExecutionException;
|
||||
|
||||
import static com.ankurm.completablefuture.Util.describe;
|
||||
|
||||
/**
|
||||
* What exceptionally, handle and whenComplete actually receive - and what join() and get() throw.
|
||||
*
|
||||
* <p>The surprise is the wrapper: depending on how a future failed and where in the chain you
|
||||
* are looking, you see either the raw exception or a CompletionException around it.
|
||||
*/
|
||||
public class ExceptionHandlingDemo {
|
||||
|
||||
static CompletableFuture<Integer> failing() {
|
||||
return CompletableFuture.supplyAsync(() -> {
|
||||
throw new IllegalStateException("boom");
|
||||
});
|
||||
}
|
||||
|
||||
static CompletableFuture<Integer> failedDirectly() {
|
||||
CompletableFuture<Integer> f = new CompletableFuture<>();
|
||||
f.completeExceptionally(new IllegalStateException("boom"));
|
||||
return f;
|
||||
}
|
||||
|
||||
public static void main(String[] args) throws Exception {
|
||||
|
||||
System.out.println("== 1. What does exceptionally() receive?");
|
||||
failing().exceptionally(ex -> {
|
||||
System.out.println("supplyAsync threw, exceptionally on same stage: " + describe(ex));
|
||||
return -1;
|
||||
}).join();
|
||||
|
||||
failedDirectly().exceptionally(ex -> {
|
||||
System.out.println("completeExceptionally(raw), same stage: " + describe(ex));
|
||||
return -1;
|
||||
}).join();
|
||||
|
||||
failedDirectly().thenApply(x -> x + 1).exceptionally(ex -> {
|
||||
System.out.println("completeExceptionally(raw), one stage later: " + describe(ex));
|
||||
return -1;
|
||||
}).join();
|
||||
|
||||
System.out.println();
|
||||
System.out.println("== 2. What do join() and get() throw?");
|
||||
try {
|
||||
failing().join();
|
||||
} catch (CompletionException e) {
|
||||
System.out.println("join(): " + describe(e));
|
||||
}
|
||||
try {
|
||||
failing().get();
|
||||
} catch (ExecutionException e) {
|
||||
System.out.println("get(): " + describe(e));
|
||||
}
|
||||
CompletableFuture<Integer> f = failing();
|
||||
try {
|
||||
f.join();
|
||||
} catch (CompletionException ignored) {
|
||||
// state() and exceptionNow() are the non-throwing way to look (JDK 19+)
|
||||
}
|
||||
System.out.println("state() = " + f.state() + ", exceptionNow() = " + describe(f.exceptionNow()));
|
||||
|
||||
System.out.println();
|
||||
System.out.println("== 3. exceptionally vs handle vs whenComplete");
|
||||
int viaExceptionally = failing().exceptionally(ex -> -1).join();
|
||||
int viaHandle = failing().handle((v, ex) -> ex == null ? v : -2).join();
|
||||
System.out.println("exceptionally(ex -> -1) -> " + viaExceptionally);
|
||||
System.out.println("handle((v, ex) -> ex==null?v:-2) -> " + viaHandle);
|
||||
|
||||
CompletableFuture<Integer> observed = failing().whenComplete((v, ex) ->
|
||||
System.out.println("whenComplete saw: " + describe(ex)));
|
||||
try {
|
||||
observed.join();
|
||||
} catch (CompletionException e) {
|
||||
System.out.println("whenComplete did not recover; join(): " + describe(e));
|
||||
}
|
||||
|
||||
System.out.println();
|
||||
System.out.println("== 4. On success, each one is a pass-through or a transformer");
|
||||
System.out.println("exceptionally on success: " + CompletableFuture.completedFuture(7).exceptionally(ex -> -1).join());
|
||||
System.out.println("handle on success: " + CompletableFuture.completedFuture(7).handle((v, ex) -> ex == null ? v * 2 : -2).join());
|
||||
System.out.println("whenComplete on success: " + CompletableFuture.completedFuture(7).whenComplete((v, ex) -> { }).join());
|
||||
|
||||
System.out.println();
|
||||
System.out.println("== 5. exceptionallyCompose: recover with another async call (JDK 12+)");
|
||||
int recovered = failing()
|
||||
.exceptionallyCompose(ex -> CompletableFuture.supplyAsync(() -> 99))
|
||||
.join();
|
||||
System.out.println("recovered value: " + recovered);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,79 @@
|
||||
package com.ankurm.completablefuture;
|
||||
|
||||
import java.util.concurrent.CompletableFuture;
|
||||
import java.util.concurrent.CountDownLatch;
|
||||
import java.util.concurrent.atomic.AtomicReference;
|
||||
|
||||
import static com.ankurm.completablefuture.Util.await;
|
||||
|
||||
/**
|
||||
* A thread blocked in join() can run the dependent stages of the future it is waiting on.
|
||||
*
|
||||
* <p>Same code, same guarantee that the dependent stage was registered before the source
|
||||
* finished. The only difference between the two loops is how main waits for the source. The counts are
|
||||
* measured, not asserted: the first loop varies from run to run, the second does not.
|
||||
*/
|
||||
public class JoinHelpsDemo {
|
||||
|
||||
public static void main(String[] args) {
|
||||
int trials = Integer.getInteger("trials", 200);
|
||||
|
||||
Thread main = Thread.currentThread();
|
||||
AtomicReference<StackTraceElement[]> sample = new AtomicReference<>();
|
||||
|
||||
int ranOnMainWhenJoining = 0;
|
||||
for (int i = 0; i < trials; i++) {
|
||||
CountDownLatch gate = new CountDownLatch(1);
|
||||
AtomicReference<Thread> ranOn = new AtomicReference<>();
|
||||
CompletableFuture<String> source = CompletableFuture.supplyAsync(() -> {
|
||||
await(gate);
|
||||
return "x";
|
||||
});
|
||||
CompletableFuture<Void> stage = source.thenAccept(v -> {
|
||||
ranOn.set(Thread.currentThread());
|
||||
if (Thread.currentThread() == main) {
|
||||
sample.compareAndSet(null, new Throwable().getStackTrace()); // keep the first one
|
||||
}
|
||||
});
|
||||
gate.countDown();
|
||||
source.join(); // main waits by calling join() on the source: this is where it may run the stage
|
||||
stage.join(); // then make sure the stage has finished, whichever thread ran it
|
||||
if (ranOn.get() == Thread.currentThread()) {
|
||||
ranOnMainWhenJoining++;
|
||||
}
|
||||
}
|
||||
|
||||
int ranOnMainWhenLatching = 0;
|
||||
for (int i = 0; i < trials; i++) {
|
||||
CountDownLatch gate = new CountDownLatch(1);
|
||||
CountDownLatch done = new CountDownLatch(1);
|
||||
AtomicReference<Thread> ranOn = new AtomicReference<>();
|
||||
CompletableFuture<String> source = CompletableFuture.supplyAsync(() -> {
|
||||
await(gate);
|
||||
return "x";
|
||||
});
|
||||
source.thenAccept(v -> {
|
||||
ranOn.set(Thread.currentThread());
|
||||
done.countDown();
|
||||
});
|
||||
gate.countDown();
|
||||
await(done); // main waits on a latch, never calls into the future
|
||||
if (ranOn.get() == Thread.currentThread()) {
|
||||
ranOnMainWhenLatching++;
|
||||
}
|
||||
}
|
||||
|
||||
System.out.println("trials per loop: " + trials);
|
||||
System.out.println("stage ran on main when main waited with join(): " + ranOnMainWhenJoining);
|
||||
System.out.println("stage ran on main when main waited on a CountDownLatch: " + ranOnMainWhenLatching);
|
||||
|
||||
StackTraceElement[] frames = sample.get();
|
||||
if (frames != null) {
|
||||
System.out.println();
|
||||
System.out.println("stack of the first stage that ran on main while it was inside join():");
|
||||
for (StackTraceElement f : frames) {
|
||||
System.out.println(" at " + f);
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
+78
@@ -0,0 +1,78 @@
|
||||
package com.ankurm.completablefuture;
|
||||
|
||||
import java.util.concurrent.CompletableFuture;
|
||||
import java.util.concurrent.ExecutorService;
|
||||
import java.util.concurrent.Executors;
|
||||
|
||||
import static com.ankurm.completablefuture.Util.sleep;
|
||||
import static com.ankurm.completablefuture.Util.timed;
|
||||
|
||||
/**
|
||||
* thenApply vs thenCompose vs thenCombine.
|
||||
*
|
||||
* <p>The rule: if your function returns a plain value, use thenApply. If it returns another
|
||||
* CompletableFuture, use thenCompose. If the two calls do not depend on each other, start both
|
||||
* first and join them with thenCombine. The last case is the one people get wrong, because
|
||||
* thenCompose compiles and returns the right answer - it is just serial.
|
||||
*/
|
||||
public class ThenApplyVsComposeDemo {
|
||||
|
||||
record User(long id, String name) {}
|
||||
|
||||
record Order(long userId, String item) {}
|
||||
|
||||
static CompletableFuture<User> fetchUser(long id, ExecutorService io) {
|
||||
return CompletableFuture.supplyAsync(() -> {
|
||||
sleep(100);
|
||||
return new User(id, "ankur");
|
||||
}, io);
|
||||
}
|
||||
|
||||
static CompletableFuture<Order> fetchLastOrder(User user, ExecutorService io) {
|
||||
return CompletableFuture.supplyAsync(() -> {
|
||||
sleep(150);
|
||||
return new Order(user.id(), "laptop");
|
||||
}, io);
|
||||
}
|
||||
|
||||
static CompletableFuture<String> fetchBanner(ExecutorService io) {
|
||||
return CompletableFuture.supplyAsync(() -> {
|
||||
sleep(120);
|
||||
return "winter-sale";
|
||||
}, io);
|
||||
}
|
||||
|
||||
public static void main(String[] args) {
|
||||
try (ExecutorService io = Executors.newFixedThreadPool(4)) {
|
||||
|
||||
System.out.println("== 1. thenApply with a function that itself returns a CompletableFuture");
|
||||
CompletableFuture<CompletableFuture<Order>> nested =
|
||||
fetchUser(1, io).thenApply(user -> fetchLastOrder(user, io));
|
||||
Object inner = nested.join();
|
||||
System.out.println("nested.join() is a: " + inner.getClass().getSimpleName());
|
||||
System.out.println("inner.join() is: " + ((CompletableFuture<?>) inner).join());
|
||||
|
||||
System.out.println();
|
||||
System.out.println("== 2. thenCompose flattens it");
|
||||
CompletableFuture<Order> flat =
|
||||
fetchUser(1, io).thenCompose(user -> fetchLastOrder(user, io));
|
||||
System.out.println("flat.join() is: " + flat.join());
|
||||
|
||||
System.out.println();
|
||||
System.out.println("== 3. Same three tools, measured (fixed pool of 4, so nothing queues)");
|
||||
timed("dependent calls: thenCompose (100 ms then 150 ms)",
|
||||
() -> fetchUser(1, io).thenCompose(user -> fetchLastOrder(user, io)));
|
||||
|
||||
timed("independent calls: start both, then thenCombine",
|
||||
() -> {
|
||||
CompletableFuture<User> user = fetchUser(1, io);
|
||||
CompletableFuture<String> banner = fetchBanner(io);
|
||||
return user.thenCombine(banner, (u, b) -> u.name() + " + " + b);
|
||||
});
|
||||
|
||||
timed("independent calls, wrongly chained with thenCompose",
|
||||
() -> fetchUser(1, io)
|
||||
.thenCompose(user -> fetchBanner(io).thenApply(b -> user.name() + " + " + b)));
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,99 @@
|
||||
package com.ankurm.completablefuture;
|
||||
|
||||
import java.util.concurrent.CancellationException;
|
||||
import java.util.concurrent.CompletableFuture;
|
||||
import java.util.concurrent.CompletionException;
|
||||
import java.util.concurrent.ExecutorService;
|
||||
import java.util.concurrent.Executors;
|
||||
import java.util.concurrent.Future;
|
||||
import java.util.concurrent.TimeUnit;
|
||||
import java.util.concurrent.TimeoutException;
|
||||
import java.util.concurrent.atomic.AtomicBoolean;
|
||||
|
||||
import static com.ankurm.completablefuture.Util.describe;
|
||||
import static com.ankurm.completablefuture.Util.sleep;
|
||||
|
||||
/**
|
||||
* orTimeout and completeOnTimeout (JDK 9+) complete the FUTURE. They do not stop the WORK.
|
||||
* cancel(true) behaves the same way, despite its argument being called mayInterruptIfRunning.
|
||||
*/
|
||||
public class TimeoutDemo {
|
||||
|
||||
public static void main(String[] args) {
|
||||
try (ExecutorService pool = Executors.newFixedThreadPool(3)) {
|
||||
|
||||
System.out.println("== 1. orTimeout: the future fails, the task keeps running");
|
||||
AtomicBoolean finished = new AtomicBoolean();
|
||||
CompletableFuture<String> slow = CompletableFuture.supplyAsync(() -> {
|
||||
sleep(600);
|
||||
finished.set(true);
|
||||
return "late result";
|
||||
}, pool).orTimeout(100, TimeUnit.MILLISECONDS);
|
||||
try {
|
||||
slow.join();
|
||||
} catch (CompletionException e) {
|
||||
System.out.println("join() after 100 ms: " + describe(e));
|
||||
}
|
||||
System.out.println("task finished right after that? " + finished.get());
|
||||
sleep(700);
|
||||
System.out.println("task finished 700 ms later? " + finished.get());
|
||||
|
||||
System.out.println();
|
||||
System.out.println("== 2. completeOnTimeout: a fallback value instead of an exception");
|
||||
String value = CompletableFuture.supplyAsync(() -> {
|
||||
sleep(600);
|
||||
return "real value";
|
||||
}, pool).completeOnTimeout("fallback value", 100, TimeUnit.MILLISECONDS).join();
|
||||
System.out.println("join() returned: " + value);
|
||||
|
||||
System.out.println();
|
||||
System.out.println("== 3. cancel(true) does not interrupt the task either");
|
||||
AtomicBoolean sawInterrupt = new AtomicBoolean();
|
||||
AtomicBoolean ranToEnd = new AtomicBoolean();
|
||||
CompletableFuture<String> cancelled = CompletableFuture.supplyAsync(() -> {
|
||||
try {
|
||||
Thread.sleep(400);
|
||||
} catch (InterruptedException e) {
|
||||
sawInterrupt.set(true);
|
||||
}
|
||||
ranToEnd.set(true);
|
||||
return "x";
|
||||
}, pool);
|
||||
sleep(50);
|
||||
System.out.println("cancel(true) returned: " + cancelled.cancel(true));
|
||||
try {
|
||||
cancelled.join();
|
||||
} catch (CancellationException e) {
|
||||
System.out.println("join(): " + e.getClass().getSimpleName());
|
||||
}
|
||||
sleep(500);
|
||||
System.out.println("task saw an interrupt? " + sawInterrupt.get());
|
||||
System.out.println("task ran to the end anyway? " + ranToEnd.get());
|
||||
|
||||
System.out.println();
|
||||
System.out.println("== 4. The fix: keep the executor's Future and cancel THAT on timeout");
|
||||
AtomicBoolean interrupted = new AtomicBoolean();
|
||||
CompletableFuture<String> result = new CompletableFuture<>();
|
||||
Future<?> handle = pool.submit(() -> {
|
||||
try {
|
||||
Thread.sleep(400);
|
||||
result.complete("done");
|
||||
} catch (InterruptedException e) {
|
||||
interrupted.set(true);
|
||||
}
|
||||
});
|
||||
result.orTimeout(100, TimeUnit.MILLISECONDS).whenComplete((v, ex) -> {
|
||||
if (ex instanceof TimeoutException) {
|
||||
handle.cancel(true);
|
||||
}
|
||||
});
|
||||
try {
|
||||
result.join();
|
||||
} catch (CompletionException e) {
|
||||
System.out.println("join(): " + describe(e));
|
||||
}
|
||||
sleep(100);
|
||||
System.out.println("task saw an interrupt? " + interrupted.get());
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,59 @@
|
||||
package com.ankurm.completablefuture;
|
||||
|
||||
import java.util.concurrent.CompletableFuture;
|
||||
import java.util.function.Supplier;
|
||||
|
||||
/** Tiny helpers shared by the demos. Nothing here is CompletableFuture-specific. */
|
||||
final class Util {
|
||||
|
||||
private Util() {}
|
||||
|
||||
/** Sleeps, and turns an interrupt into an unchecked exception so lambdas stay readable. */
|
||||
static void sleep(long ms) {
|
||||
try {
|
||||
Thread.sleep(ms);
|
||||
} catch (InterruptedException e) {
|
||||
Thread.currentThread().interrupt();
|
||||
throw new IllegalStateException("interrupted while sleeping", e);
|
||||
}
|
||||
}
|
||||
|
||||
/** Waits on a latch, turning an interrupt into an unchecked exception. */
|
||||
static void await(java.util.concurrent.CountDownLatch latch) {
|
||||
try {
|
||||
latch.await();
|
||||
} catch (InterruptedException e) {
|
||||
Thread.currentThread().interrupt();
|
||||
throw new IllegalStateException("interrupted while waiting", e);
|
||||
}
|
||||
}
|
||||
|
||||
/** Thread name, with virtual threads (which have an empty name) labelled explicitly. */
|
||||
static String threadName() {
|
||||
Thread t = Thread.currentThread();
|
||||
return t.isVirtual() ? "virtual-thread" : t.getName();
|
||||
}
|
||||
|
||||
/** Runs the supplier, joins the future it returns, and prints the result with wall-clock time. */
|
||||
static <T> T timed(String label, Supplier<CompletableFuture<T>> work) {
|
||||
long t0 = System.nanoTime();
|
||||
T result = work.get().join();
|
||||
long ms = (System.nanoTime() - t0) / 1_000_000;
|
||||
System.out.printf("%-58s -> %-34s %5d ms%n", label, result, ms);
|
||||
return result;
|
||||
}
|
||||
|
||||
/** One-line description of a throwable: its class, message, and cause chain head. */
|
||||
static String describe(Throwable ex) {
|
||||
if (ex == null) {
|
||||
return "null";
|
||||
}
|
||||
String s = ex.getClass().getSimpleName();
|
||||
if (ex.getCause() != null) {
|
||||
s += " <- cause " + ex.getCause().getClass().getSimpleName() + ": " + ex.getCause().getMessage();
|
||||
} else if (ex.getMessage() != null) {
|
||||
s += ": " + ex.getMessage();
|
||||
}
|
||||
return s;
|
||||
}
|
||||
}
|
||||
+101
@@ -0,0 +1,101 @@
|
||||
package com.ankurm.completablefuture;
|
||||
|
||||
import java.security.MessageDigest;
|
||||
import java.security.NoSuchAlgorithmException;
|
||||
import java.util.List;
|
||||
import java.util.concurrent.CompletableFuture;
|
||||
import java.util.concurrent.Executor;
|
||||
import java.util.concurrent.ExecutorService;
|
||||
import java.util.concurrent.Executors;
|
||||
import java.util.concurrent.ForkJoinPool;
|
||||
import java.util.function.Supplier;
|
||||
import java.util.stream.IntStream;
|
||||
|
||||
import static com.ankurm.completablefuture.Util.sleep;
|
||||
|
||||
/**
|
||||
* Where do virtual threads win? Blocking work, by a lot. CPU-bound work, not at all.
|
||||
*
|
||||
* <p>Wall-clock numbers, one run each after a warm-up. Indicative, not a JMH result: the figures
|
||||
* to trust are the ratios, and the figures to distrust are the absolute milliseconds.
|
||||
*/
|
||||
public class VirtualThreadsBenchmark {
|
||||
|
||||
static final int BLOCKING_TASKS = Integer.getInteger("blockingTasks", 300);
|
||||
static final int BLOCKING_MS = Integer.getInteger("blockingMs", 50);
|
||||
static final int CPU_TASKS = Integer.getInteger("cpuTasks", 16);
|
||||
static final int CPU_ROUNDS = Integer.getInteger("cpuRounds", 2_000_000);
|
||||
|
||||
/** Starts every task via supplyAsync, waits for all, returns elapsed milliseconds. */
|
||||
static long run(int tasks, Supplier<Integer> body, Executor executor) {
|
||||
long t0 = System.nanoTime();
|
||||
List<CompletableFuture<Integer>> futures = IntStream.range(0, tasks)
|
||||
.mapToObj(i -> executor == null
|
||||
? CompletableFuture.supplyAsync(body)
|
||||
: CompletableFuture.supplyAsync(body, executor))
|
||||
.toList();
|
||||
CompletableFuture.allOf(futures.toArray(CompletableFuture[]::new)).join();
|
||||
return (System.nanoTime() - t0) / 1_000_000;
|
||||
}
|
||||
|
||||
static int blocking() {
|
||||
sleep(BLOCKING_MS);
|
||||
return 1;
|
||||
}
|
||||
|
||||
static int cpu() {
|
||||
try {
|
||||
MessageDigest md = MessageDigest.getInstance("SHA-256");
|
||||
byte[] data = new byte[32];
|
||||
for (int i = 0; i < CPU_ROUNDS; i++) {
|
||||
data = md.digest(data);
|
||||
}
|
||||
return data[0];
|
||||
} catch (NoSuchAlgorithmException e) {
|
||||
throw new IllegalStateException(e);
|
||||
}
|
||||
}
|
||||
|
||||
static void row(String label, long ms) {
|
||||
System.out.printf(" %-46s %7d ms%n", label, ms);
|
||||
}
|
||||
|
||||
public static void main(String[] args) {
|
||||
int cores = Runtime.getRuntime().availableProcessors();
|
||||
System.out.println("availableProcessors = " + cores);
|
||||
System.out.println("common pool parallelism = " + ForkJoinPool.getCommonPoolParallelism());
|
||||
|
||||
// Warm-up so class loading and JIT do not land in the first row.
|
||||
try (ExecutorService warm = Executors.newVirtualThreadPerTaskExecutor()) {
|
||||
run(50, VirtualThreadsBenchmark::blocking, warm);
|
||||
run(2, VirtualThreadsBenchmark::cpu, warm);
|
||||
}
|
||||
|
||||
System.out.println();
|
||||
System.out.printf("== Blocking work: %d tasks, each sleeping %d ms (a stand-in for a remote call)%n",
|
||||
BLOCKING_TASKS, BLOCKING_MS);
|
||||
row("default async pool (no executor argument)", run(BLOCKING_TASKS, VirtualThreadsBenchmark::blocking, null));
|
||||
try (ExecutorService fixed50 = Executors.newFixedThreadPool(50)) {
|
||||
row("fixed pool, 50 threads", run(BLOCKING_TASKS, VirtualThreadsBenchmark::blocking, fixed50));
|
||||
}
|
||||
try (ExecutorService fixed200 = Executors.newFixedThreadPool(200)) {
|
||||
row("fixed pool, 200 threads", run(BLOCKING_TASKS, VirtualThreadsBenchmark::blocking, fixed200));
|
||||
}
|
||||
try (ExecutorService virtual = Executors.newVirtualThreadPerTaskExecutor()) {
|
||||
row("virtual thread per task", run(BLOCKING_TASKS, VirtualThreadsBenchmark::blocking, virtual));
|
||||
}
|
||||
|
||||
System.out.println();
|
||||
System.out.printf("== CPU-bound work: %d tasks, each %,d rounds of SHA-256%n", CPU_TASKS, CPU_ROUNDS);
|
||||
long t0 = System.nanoTime();
|
||||
IntStream.range(0, CPU_TASKS).forEach(i -> cpu());
|
||||
row("sequential, one thread (baseline)", (System.nanoTime() - t0) / 1_000_000);
|
||||
row("default async pool (no executor argument)", run(CPU_TASKS, VirtualThreadsBenchmark::cpu, null));
|
||||
try (ExecutorService fixed = Executors.newFixedThreadPool(cores)) {
|
||||
row("fixed pool, " + cores + " threads (= cores)", run(CPU_TASKS, VirtualThreadsBenchmark::cpu, fixed));
|
||||
}
|
||||
try (ExecutorService virtual = Executors.newVirtualThreadPerTaskExecutor()) {
|
||||
row("virtual thread per task", run(CPU_TASKS, VirtualThreadsBenchmark::cpu, virtual));
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,91 @@
|
||||
package com.ankurm.completablefuture;
|
||||
|
||||
import java.util.Map;
|
||||
import java.util.concurrent.CompletableFuture;
|
||||
import java.util.concurrent.ConcurrentHashMap;
|
||||
import java.util.concurrent.CountDownLatch;
|
||||
import java.util.concurrent.ExecutorService;
|
||||
import java.util.concurrent.Executors;
|
||||
import java.util.concurrent.ForkJoinPool;
|
||||
import java.util.concurrent.atomic.AtomicInteger;
|
||||
|
||||
import static com.ankurm.completablefuture.Util.await;
|
||||
import static com.ankurm.completablefuture.Util.threadName;
|
||||
|
||||
/**
|
||||
* Which thread runs each stage?
|
||||
*
|
||||
* <p>The answer depends on two things: whether the stage was registered before or after the
|
||||
* previous stage finished, and whether you used the Async variant (and which executor).
|
||||
*
|
||||
* <p>Two details keep the transcript stable. A latch holds the first stage open until every
|
||||
* dependent stage is registered, so "registered before it finished" is guaranteed. And main waits
|
||||
* on a second latch instead of calling join(): a thread blocked in join() can run dependent stages
|
||||
* itself (see JoinHelpsDemo), which would make this output vary between runs.
|
||||
*/
|
||||
public class WhichThreadDemo {
|
||||
|
||||
private static final Map<String, String> lines = new ConcurrentHashMap<>();
|
||||
|
||||
/** Records which thread this stage ran on, then counts the latch down. */
|
||||
static void record(String key, String label, CountDownLatch done) {
|
||||
lines.put(key, String.format("%-52s ran on %s", label, threadName()));
|
||||
done.countDown();
|
||||
}
|
||||
|
||||
public static void main(String[] args) {
|
||||
System.out.println("availableProcessors = " + Runtime.getRuntime().availableProcessors());
|
||||
System.out.println("common pool parallelism = " + ForkJoinPool.getCommonPoolParallelism());
|
||||
System.out.println("caller thread = " + threadName());
|
||||
System.out.println();
|
||||
|
||||
AtomicInteger n = new AtomicInteger();
|
||||
try (ExecutorService mine = Executors.newFixedThreadPool(2, r -> new Thread(r, "my-pool-" + n.incrementAndGet()))) {
|
||||
|
||||
System.out.println("== Stage registered WHILE the previous stage is still running");
|
||||
CountDownLatch gate = new CountDownLatch(1);
|
||||
CountDownLatch done = new CountDownLatch(4);
|
||||
CompletableFuture<String> slow = CompletableFuture.supplyAsync(() -> {
|
||||
await(gate);
|
||||
record("1", "supplyAsync body", done);
|
||||
return "x";
|
||||
});
|
||||
slow.thenApply(v -> { record("2", "thenApply (registered before slow finished)", done); return v; });
|
||||
slow.thenApplyAsync(v -> { record("3", "thenApplyAsync (no executor)", done); return v; });
|
||||
slow.thenApplyAsync(v -> { record("4", "thenApplyAsync (executor = mine)", done); return v; }, mine);
|
||||
gate.countDown(); // every stage is registered; now let slow finish
|
||||
await(done);
|
||||
for (String k : new String[] {"1", "2", "3", "4"}) {
|
||||
System.out.println(lines.get(k));
|
||||
}
|
||||
while (!slow.isDone()) {
|
||||
Thread.yield(); // isDone() does not run any stage, unlike join()
|
||||
}
|
||||
|
||||
System.out.println();
|
||||
System.out.println("== Stage registered AFTER the previous stage finished");
|
||||
CountDownLatch after = new CountDownLatch(2);
|
||||
slow.thenApply(v -> { record("5", "thenApply (registered after slow finished)", after); return v; });
|
||||
CompletableFuture.completedFuture("x")
|
||||
.thenApply(v -> { record("6", "thenApply on completedFuture(..)", after); return v; });
|
||||
await(after);
|
||||
System.out.println(lines.get("5"));
|
||||
System.out.println(lines.get("6"));
|
||||
|
||||
System.out.println();
|
||||
System.out.println("== Supplying with your own executor");
|
||||
CountDownLatch gate2 = new CountDownLatch(1);
|
||||
CountDownLatch done2 = new CountDownLatch(2);
|
||||
CompletableFuture<String> body = CompletableFuture.supplyAsync(() -> {
|
||||
await(gate2);
|
||||
record("7", "supplyAsync(.., mine) body", done2);
|
||||
return "x";
|
||||
}, mine);
|
||||
body.thenApply(v -> { record("8", "thenApply after supplyAsync(.., mine)", done2); return v; });
|
||||
gate2.countDown();
|
||||
await(done2);
|
||||
System.out.println(lines.get("7"));
|
||||
System.out.println(lines.get("8"));
|
||||
}
|
||||
}
|
||||
}
|
||||
+322
@@ -0,0 +1,322 @@
|
||||
package com.ankurm.completablefuture;
|
||||
|
||||
import org.junit.jupiter.api.Test;
|
||||
|
||||
import java.util.List;
|
||||
import java.util.concurrent.CancellationException;
|
||||
import java.util.concurrent.CompletableFuture;
|
||||
import java.util.concurrent.CompletionException;
|
||||
import java.util.concurrent.CountDownLatch;
|
||||
import java.util.concurrent.ExecutionException;
|
||||
import java.util.concurrent.ExecutorService;
|
||||
import java.util.concurrent.Executors;
|
||||
import java.util.concurrent.Future;
|
||||
import java.util.concurrent.TimeUnit;
|
||||
import java.util.concurrent.TimeoutException;
|
||||
import java.util.concurrent.atomic.AtomicBoolean;
|
||||
import java.util.concurrent.atomic.AtomicReference;
|
||||
|
||||
import static com.ankurm.completablefuture.Util.sleep;
|
||||
import static org.junit.jupiter.api.Assertions.*;
|
||||
|
||||
/**
|
||||
* Pins the behaviours the article states. Timing assertions use generous bounds: they check the
|
||||
* SHAPE (waited for the slow one, failed fast) and not an exact millisecond figure.
|
||||
*/
|
||||
class CompletableFutureContractTest {
|
||||
|
||||
// ---- thenApply / thenCompose ------------------------------------------------------------
|
||||
|
||||
@Test
|
||||
void thenApplyWithAFutureReturningFunctionGivesANestedFuture() {
|
||||
CompletableFuture<CompletableFuture<Integer>> nested =
|
||||
CompletableFuture.completedFuture(1).thenApply(x -> CompletableFuture.completedFuture(x + 1));
|
||||
assertInstanceOf(CompletableFuture.class, nested.join());
|
||||
}
|
||||
|
||||
@Test
|
||||
void thenComposeFlattensIt() {
|
||||
CompletableFuture<Integer> flat =
|
||||
CompletableFuture.completedFuture(1).thenCompose(x -> CompletableFuture.completedFuture(x + 1));
|
||||
assertEquals(2, flat.join());
|
||||
}
|
||||
|
||||
@Test
|
||||
void independentCallsChainedWithThenComposeAreSerial() throws Exception {
|
||||
try (ExecutorService io = Executors.newFixedThreadPool(4)) {
|
||||
long t0 = System.nanoTime();
|
||||
CompletableFuture.supplyAsync(() -> { sleep(150); return 1; }, io)
|
||||
.thenCompose(a -> CompletableFuture.supplyAsync(() -> { sleep(150); return a + 1; }, io))
|
||||
.join();
|
||||
long chainedMs = (System.nanoTime() - t0) / 1_000_000;
|
||||
|
||||
long t1 = System.nanoTime();
|
||||
CompletableFuture<Integer> x = CompletableFuture.supplyAsync(() -> { sleep(150); return 1; }, io);
|
||||
CompletableFuture<Integer> y = CompletableFuture.supplyAsync(() -> { sleep(150); return 1; }, io);
|
||||
x.thenCombine(y, Integer::sum).join();
|
||||
long combinedMs = (System.nanoTime() - t1) / 1_000_000;
|
||||
|
||||
assertTrue(chainedMs >= 290, "chained should be about the sum, was " + chainedMs);
|
||||
assertTrue(combinedMs < 280, "combined should be about the max, was " + combinedMs);
|
||||
}
|
||||
}
|
||||
|
||||
// ---- which thread -----------------------------------------------------------------------
|
||||
|
||||
@Test
|
||||
void stageRegisteredAfterCompletionRunsOnTheCallingThread() {
|
||||
AtomicReference<Thread> ranOn = new AtomicReference<>();
|
||||
CompletableFuture.completedFuture("x").thenApply(v -> { ranOn.set(Thread.currentThread()); return v; }).join();
|
||||
assertSame(Thread.currentThread(), ranOn.get());
|
||||
}
|
||||
|
||||
@Test
|
||||
void stageRegisteredBeforeCompletionRunsOnTheCompletingThread() {
|
||||
try (ExecutorService pool = Executors.newFixedThreadPool(1, r -> new Thread(r, "completer"))) {
|
||||
AtomicReference<String> ranOn = new AtomicReference<>();
|
||||
CountDownLatch gate = new CountDownLatch(1);
|
||||
CountDownLatch done = new CountDownLatch(1);
|
||||
CompletableFuture.supplyAsync(() -> { Util.await(gate); return "x"; }, pool)
|
||||
.thenApply(v -> { ranOn.set(Thread.currentThread().getName()); done.countDown(); return v; });
|
||||
gate.countDown(); // the dependent stage is registered; now let the first one finish
|
||||
Util.await(done); // wait on a latch: calling join() here could run the stage on this thread
|
||||
assertEquals("completer", ranOn.get());
|
||||
}
|
||||
}
|
||||
|
||||
@Test
|
||||
void mainNeverRunsARegisteredStageWhenItWaitsOnALatch() {
|
||||
for (int i = 0; i < 50; i++) {
|
||||
CountDownLatch gate = new CountDownLatch(1);
|
||||
CountDownLatch done = new CountDownLatch(1);
|
||||
AtomicReference<Thread> ranOn = new AtomicReference<>();
|
||||
CompletableFuture.supplyAsync(() -> { Util.await(gate); return "x"; })
|
||||
.thenAccept(v -> { ranOn.set(Thread.currentThread()); done.countDown(); });
|
||||
gate.countDown();
|
||||
Util.await(done);
|
||||
assertNotSame(Thread.currentThread(), ranOn.get());
|
||||
}
|
||||
}
|
||||
|
||||
@Test
|
||||
void thenApplyAsyncWithExecutorRunsOnThatExecutor() {
|
||||
try (ExecutorService pool = Executors.newFixedThreadPool(1, r -> new Thread(r, "mine"))) {
|
||||
String name = CompletableFuture.completedFuture("x")
|
||||
.thenApplyAsync(v -> Thread.currentThread().getName(), pool).join();
|
||||
assertEquals("mine", name);
|
||||
}
|
||||
}
|
||||
|
||||
// ---- exceptions -------------------------------------------------------------------------
|
||||
|
||||
@Test
|
||||
void exceptionallyOnAFailedSupplyAsyncSeesTheCompletionExceptionWrapper() {
|
||||
Throwable seen = CompletableFuture.<Integer>supplyAsync(() -> { throw new IllegalStateException("boom"); })
|
||||
.handle((v, ex) -> ex).join();
|
||||
assertInstanceOf(CompletionException.class, seen);
|
||||
assertInstanceOf(IllegalStateException.class, seen.getCause());
|
||||
}
|
||||
|
||||
@Test
|
||||
void completeExceptionallyIsSeenRawOnTheSameStageAndWrappedDownstream() {
|
||||
CompletableFuture<Integer> f = new CompletableFuture<>();
|
||||
f.completeExceptionally(new IllegalStateException("boom"));
|
||||
assertInstanceOf(IllegalStateException.class, f.handle((v, ex) -> ex).join());
|
||||
assertInstanceOf(CompletionException.class, f.thenApply(x -> x + 1).handle((v, ex) -> ex).join());
|
||||
}
|
||||
|
||||
@Test
|
||||
void joinThrowsCompletionExceptionAndGetThrowsExecutionException() {
|
||||
CompletableFuture<Integer> f = CompletableFuture.failedFuture(new IllegalStateException("boom"));
|
||||
CompletionException ce = assertThrows(CompletionException.class, f::join);
|
||||
ExecutionException ee = assertThrows(ExecutionException.class, f::get);
|
||||
assertInstanceOf(IllegalStateException.class, ce.getCause());
|
||||
assertInstanceOf(IllegalStateException.class, ee.getCause());
|
||||
}
|
||||
|
||||
@Test
|
||||
void dependentStagesAreSkippedAfterAFailure() {
|
||||
AtomicBoolean ran = new AtomicBoolean();
|
||||
CompletableFuture<Integer> f = CompletableFuture.<Integer>failedFuture(new IllegalStateException("boom"))
|
||||
.thenApply(x -> { ran.set(true); return x + 1; })
|
||||
.thenApply(x -> { ran.set(true); return x * 2; });
|
||||
assertTrue(f.isCompletedExceptionally());
|
||||
assertFalse(ran.get(), "thenApply functions must not run once an earlier stage has failed");
|
||||
}
|
||||
|
||||
@Test
|
||||
void whenCompleteObservesButDoesNotRecover() {
|
||||
AtomicBoolean observed = new AtomicBoolean();
|
||||
CompletableFuture<Integer> f = CompletableFuture.<Integer>failedFuture(new IllegalStateException("boom"))
|
||||
.whenComplete((v, ex) -> observed.set(ex != null));
|
||||
assertTrue(observed.get());
|
||||
assertTrue(f.isCompletedExceptionally());
|
||||
}
|
||||
|
||||
@Test
|
||||
void handleAndExceptionallyRecover() {
|
||||
CompletableFuture<Integer> bad = CompletableFuture.failedFuture(new IllegalStateException("boom"));
|
||||
assertEquals(-1, bad.exceptionally(ex -> -1).join());
|
||||
assertEquals(-2, bad.handle((v, ex) -> ex == null ? v : -2).join());
|
||||
}
|
||||
|
||||
@Test
|
||||
void exceptionallyComposeRecoversWithAnotherFuture() {
|
||||
int v = CompletableFuture.<Integer>failedFuture(new IllegalStateException("boom"))
|
||||
.exceptionallyCompose(ex -> CompletableFuture.completedFuture(99)).join();
|
||||
assertEquals(99, v);
|
||||
}
|
||||
|
||||
// ---- timeouts and cancellation ----------------------------------------------------------
|
||||
|
||||
@Test
|
||||
void orTimeoutFailsTheFutureWithTimeoutException() {
|
||||
CompletableFuture<String> f = new CompletableFuture<String>().orTimeout(50, TimeUnit.MILLISECONDS);
|
||||
CompletionException ce = assertThrows(CompletionException.class, f::join);
|
||||
assertInstanceOf(TimeoutException.class, ce.getCause());
|
||||
}
|
||||
|
||||
@Test
|
||||
void completeOnTimeoutSuppliesTheFallback() {
|
||||
String v = new CompletableFuture<String>().completeOnTimeout("fallback", 50, TimeUnit.MILLISECONDS).join();
|
||||
assertEquals("fallback", v);
|
||||
}
|
||||
|
||||
@Test
|
||||
void orTimeoutDoesNotStopTheRunningTask() throws Exception {
|
||||
try (ExecutorService pool = Executors.newFixedThreadPool(1)) {
|
||||
CountDownLatch finished = new CountDownLatch(1);
|
||||
CompletableFuture<String> f = CompletableFuture.supplyAsync(() -> {
|
||||
sleep(300);
|
||||
finished.countDown();
|
||||
return "late";
|
||||
}, pool).orTimeout(50, TimeUnit.MILLISECONDS);
|
||||
assertThrows(CompletionException.class, f::join);
|
||||
assertEquals(1, finished.getCount(), "task should still be running right after the timeout");
|
||||
assertTrue(finished.await(2, TimeUnit.SECONDS), "task should run to completion");
|
||||
}
|
||||
}
|
||||
|
||||
@Test
|
||||
void cancelTrueDoesNotInterruptTheTask() throws Exception {
|
||||
try (ExecutorService pool = Executors.newFixedThreadPool(1)) {
|
||||
AtomicBoolean sawInterrupt = new AtomicBoolean();
|
||||
CountDownLatch ran = new CountDownLatch(1);
|
||||
CompletableFuture<String> f = CompletableFuture.supplyAsync(() -> {
|
||||
try {
|
||||
Thread.sleep(300);
|
||||
} catch (InterruptedException e) {
|
||||
sawInterrupt.set(true);
|
||||
}
|
||||
ran.countDown();
|
||||
return "x";
|
||||
}, pool);
|
||||
sleep(30);
|
||||
assertTrue(f.cancel(true));
|
||||
assertThrows(CancellationException.class, f::join);
|
||||
assertTrue(ran.await(2, TimeUnit.SECONDS));
|
||||
assertFalse(sawInterrupt.get());
|
||||
}
|
||||
}
|
||||
|
||||
@Test
|
||||
void cancellingTheExecutorFutureDoesInterruptTheTask() throws Exception {
|
||||
try (ExecutorService pool = Executors.newFixedThreadPool(1)) {
|
||||
CountDownLatch interrupted = new CountDownLatch(1);
|
||||
Future<?> handle = pool.submit(() -> {
|
||||
try {
|
||||
Thread.sleep(2_000);
|
||||
} catch (InterruptedException e) {
|
||||
interrupted.countDown();
|
||||
}
|
||||
});
|
||||
sleep(30);
|
||||
handle.cancel(true);
|
||||
assertTrue(interrupted.await(1, TimeUnit.SECONDS));
|
||||
}
|
||||
}
|
||||
|
||||
// ---- allOf / anyOf ----------------------------------------------------------------------
|
||||
|
||||
@Test
|
||||
void allOfWaitsForTheSlowOneEvenAfterAnEarlyFailure() {
|
||||
try (ExecutorService pool = Executors.newFixedThreadPool(2)) {
|
||||
CompletableFuture<String> early = CompletableFuture.supplyAsync(() -> {
|
||||
sleep(30);
|
||||
throw new IllegalStateException("early");
|
||||
}, pool);
|
||||
AtomicBoolean slowDone = new AtomicBoolean();
|
||||
CompletableFuture<String> slow = CompletableFuture.supplyAsync(() -> {
|
||||
sleep(300);
|
||||
slowDone.set(true);
|
||||
return "ok";
|
||||
}, pool);
|
||||
assertThrows(CompletionException.class, () -> CompletableFuture.allOf(early, slow).join());
|
||||
assertTrue(slowDone.get(), "allOf only fails after every input has completed");
|
||||
}
|
||||
}
|
||||
|
||||
@Test
|
||||
void failFastHelperFailsBeforeTheSlowOneFinishes() {
|
||||
try (ExecutorService pool = Executors.newFixedThreadPool(2)) {
|
||||
CompletableFuture<String> early = AllOfAnyOfDemo.failAfter(30, pool);
|
||||
AtomicBoolean slowDone = new AtomicBoolean();
|
||||
CompletableFuture<String> slow = CompletableFuture.supplyAsync(() -> {
|
||||
sleep(300);
|
||||
slowDone.set(true);
|
||||
return "ok";
|
||||
}, pool);
|
||||
assertThrows(CompletionException.class, () -> AllOfAnyOfDemo.allOrFailFast(List.of(early, slow)).join());
|
||||
assertFalse(slowDone.get(), "the slow task is still running when the helper fails");
|
||||
}
|
||||
}
|
||||
|
||||
@Test
|
||||
void anyOfCountsAFailureAsTheFirstCompletion() {
|
||||
try (ExecutorService pool = Executors.newFixedThreadPool(2)) {
|
||||
CompletableFuture<Object> any = CompletableFuture.anyOf(
|
||||
AllOfAnyOfDemo.failAfter(20, pool), AllOfAnyOfDemo.after(150, "ok", pool));
|
||||
assertThrows(CompletionException.class, any::join);
|
||||
}
|
||||
}
|
||||
|
||||
@Test
|
||||
void firstSuccessSkipsFailures() {
|
||||
try (ExecutorService pool = Executors.newFixedThreadPool(3)) {
|
||||
String v = AllOfAnyOfDemo.firstSuccess(List.of(
|
||||
AllOfAnyOfDemo.failAfter(20, pool), AllOfAnyOfDemo.after(100, "ok", pool))).join();
|
||||
assertEquals("ok", v);
|
||||
}
|
||||
}
|
||||
|
||||
@Test
|
||||
void firstSuccessFailsOnlyWhenEveryInputFails() {
|
||||
try (ExecutorService pool = Executors.newFixedThreadPool(2)) {
|
||||
CompletableFuture<String> f = AllOfAnyOfDemo.firstSuccess(List.of(
|
||||
AllOfAnyOfDemo.failAfter(10, pool), AllOfAnyOfDemo.failAfter(20, pool)));
|
||||
assertThrows(CompletionException.class, f::join);
|
||||
}
|
||||
}
|
||||
|
||||
// ---- virtual threads --------------------------------------------------------------------
|
||||
|
||||
@Test
|
||||
void virtualThreadExecutorRunsStagesOnVirtualThreads() {
|
||||
try (ExecutorService vt = Executors.newVirtualThreadPerTaskExecutor()) {
|
||||
boolean virtual = CompletableFuture.supplyAsync(() -> Thread.currentThread().isVirtual(), vt).join();
|
||||
assertTrue(virtual);
|
||||
}
|
||||
}
|
||||
|
||||
@Test
|
||||
void manyBlockingTasksFinishInAboutOneTaskTimeOnVirtualThreads() {
|
||||
try (ExecutorService vt = Executors.newVirtualThreadPerTaskExecutor()) {
|
||||
long t0 = System.nanoTime();
|
||||
List<CompletableFuture<Integer>> fs = java.util.stream.IntStream.range(0, 1_000)
|
||||
.mapToObj(i -> CompletableFuture.supplyAsync(() -> { sleep(100); return 1; }, vt)).toList();
|
||||
CompletableFuture.allOf(fs.toArray(CompletableFuture[]::new)).join();
|
||||
long ms = (System.nanoTime() - t0) / 1_000_000;
|
||||
assertTrue(ms < 1_500, "1,000 x 100 ms sleeps on virtual threads should not take " + ms + " ms");
|
||||
}
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user