From 9c2ae10d7f3b27a1d507b4755ae961207871f70b Mon Sep 17 00:00:00 2001 From: Ankur Mhatre Date: Sun, 22 Nov 2026 18:56:47 +0530 Subject: [PATCH] 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 Claude-Session: https://claude.ai/code/session_017ic4b3dRuKRhrHFPzWSSxr --- README.md | 1 + completablefuture/README.md | 76 +++++ .../output/01-thenapply-vs-thencompose.txt | 11 + completablefuture/output/02-which-thread.txt | 17 + completablefuture/output/03-join-helps.txt | 11 + .../output/04-exception-handling.txt | 23 ++ .../output/05-timeouts-and-cancel.txt | 17 + completablefuture/output/06-allof-anyof.txt | 19 ++ .../output/07-virtual-threads-timings.txt | 14 + .../08-structured-scope-without-preview.txt | 9 + completablefuture/output/09-tests.txt | 3 + completablefuture/pom.xml | 43 +++ completablefuture/scripts/compile-broken.sh | 8 + completablefuture/scripts/run-all.sh | 18 + .../broken/StructuredScopeWithoutPreview.java | 15 + .../completablefuture/AllOfAnyOfDemo.java | 125 +++++++ .../ExceptionHandlingDemo.java | 95 ++++++ .../completablefuture/JoinHelpsDemo.java | 79 +++++ .../ThenApplyVsComposeDemo.java | 78 +++++ .../ankurm/completablefuture/TimeoutDemo.java | 99 ++++++ .../com/ankurm/completablefuture/Util.java | 59 ++++ .../VirtualThreadsBenchmark.java | 101 ++++++ .../completablefuture/WhichThreadDemo.java | 91 +++++ .../CompletableFutureContractTest.java | 322 ++++++++++++++++++ pom.xml | 1 + 25 files changed, 1335 insertions(+) create mode 100644 completablefuture/README.md create mode 100644 completablefuture/output/01-thenapply-vs-thencompose.txt create mode 100644 completablefuture/output/02-which-thread.txt create mode 100644 completablefuture/output/03-join-helps.txt create mode 100644 completablefuture/output/04-exception-handling.txt create mode 100644 completablefuture/output/05-timeouts-and-cancel.txt create mode 100644 completablefuture/output/06-allof-anyof.txt create mode 100644 completablefuture/output/07-virtual-threads-timings.txt create mode 100644 completablefuture/output/08-structured-scope-without-preview.txt create mode 100644 completablefuture/output/09-tests.txt create mode 100644 completablefuture/pom.xml create mode 100755 completablefuture/scripts/compile-broken.sh create mode 100755 completablefuture/scripts/run-all.sh create mode 100644 completablefuture/src/broken/StructuredScopeWithoutPreview.java create mode 100644 completablefuture/src/main/java/com/ankurm/completablefuture/AllOfAnyOfDemo.java create mode 100644 completablefuture/src/main/java/com/ankurm/completablefuture/ExceptionHandlingDemo.java create mode 100644 completablefuture/src/main/java/com/ankurm/completablefuture/JoinHelpsDemo.java create mode 100644 completablefuture/src/main/java/com/ankurm/completablefuture/ThenApplyVsComposeDemo.java create mode 100644 completablefuture/src/main/java/com/ankurm/completablefuture/TimeoutDemo.java create mode 100644 completablefuture/src/main/java/com/ankurm/completablefuture/Util.java create mode 100644 completablefuture/src/main/java/com/ankurm/completablefuture/VirtualThreadsBenchmark.java create mode 100644 completablefuture/src/main/java/com/ankurm/completablefuture/WhichThreadDemo.java create mode 100644 completablefuture/src/test/java/com/ankurm/completablefuture/CompletableFutureContractTest.java diff --git a/README.md b/README.md index 8b577a2..665084c 100644 --- a/README.md +++ b/README.md @@ -35,6 +35,7 @@ article; each module's own README has that article's version table, quickstart, | [`bufferedreader`](bufferedreader/) | Java BufferedReader: Read a File Line by Line (vs Scanner, Files.lines and readAllLines) | | [`parallel-streams`](parallel-streams/) | Java Parallel Streams: When They're Slower (JMH Benchmarks and the Common Pool) | | [`random`](random/) | Random vs ThreadLocalRandom vs SecureRandom vs RandomGenerator in Java | +| [`completablefuture`](completablefuture/) | CompletableFuture in Java: thenApply vs thenCompose, allOf, Exceptions and Timeouts (and When Virtual Threads Win) | ## License diff --git a/completablefuture/README.md b/completablefuture/README.md new file mode 100644 index 0000000..8e4214e --- /dev/null +++ b/completablefuture/README.md @@ -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 | `25` | +| 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). diff --git a/completablefuture/output/01-thenapply-vs-thencompose.txt b/completablefuture/output/01-thenapply-vs-thencompose.txt new file mode 100644 index 0000000..3f8fee6 --- /dev/null +++ b/completablefuture/output/01-thenapply-vs-thencompose.txt @@ -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 diff --git a/completablefuture/output/02-which-thread.txt b/completablefuture/output/02-which-thread.txt new file mode 100644 index 0000000..fbf5550 --- /dev/null +++ b/completablefuture/output/02-which-thread.txt @@ -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 diff --git a/completablefuture/output/03-join-helps.txt b/completablefuture/output/03-join-helps.txt new file mode 100644 index 0000000..2d18ec1 --- /dev/null +++ b/completablefuture/output/03-join-helps.txt @@ -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) diff --git a/completablefuture/output/04-exception-handling.txt b/completablefuture/output/04-exception-handling.txt new file mode 100644 index 0000000..31177bf --- /dev/null +++ b/completablefuture/output/04-exception-handling.txt @@ -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 diff --git a/completablefuture/output/05-timeouts-and-cancel.txt b/completablefuture/output/05-timeouts-and-cancel.txt new file mode 100644 index 0000000..e99d745 --- /dev/null +++ b/completablefuture/output/05-timeouts-and-cancel.txt @@ -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 diff --git a/completablefuture/output/06-allof-anyof.txt b/completablefuture/output/06-allof-anyof.txt new file mode 100644 index 0000000..f3b205f --- /dev/null +++ b/completablefuture/output/06-allof-anyof.txt @@ -0,0 +1,19 @@ +== 1. allOf returns CompletableFuture - 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 diff --git a/completablefuture/output/07-virtual-threads-timings.txt b/completablefuture/output/07-virtual-threads-timings.txt new file mode 100644 index 0000000..45b0e89 --- /dev/null +++ b/completablefuture/output/07-virtual-threads-timings.txt @@ -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 diff --git a/completablefuture/output/08-structured-scope-without-preview.txt b/completablefuture/output/08-structured-scope-without-preview.txt new file mode 100644 index 0000000..b434324 --- /dev/null +++ b/completablefuture/output/08-structured-scope-without-preview.txt @@ -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 diff --git a/completablefuture/output/09-tests.txt b/completablefuture/output/09-tests.txt new file mode 100644 index 0000000..75d7ee9 --- /dev/null +++ b/completablefuture/output/09-tests.txt @@ -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 diff --git a/completablefuture/pom.xml b/completablefuture/pom.xml new file mode 100644 index 0000000..31666cf --- /dev/null +++ b/completablefuture/pom.xml @@ -0,0 +1,43 @@ + + + 4.0.0 + + + com.ankurm + java-core-examples + 1.0 + + + completablefuture + completablefuture + 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. + + + + org.junit.jupiter + junit-jupiter + 6.1.3 + test + + + + + + + org.apache.maven.plugins + maven-compiler-plugin + 3.16.0 + + 25 + + + + org.apache.maven.plugins + maven-surefire-plugin + 3.6.1 + + + + diff --git a/completablefuture/scripts/compile-broken.sh b/completablefuture/scripts/compile-broken.sh new file mode 100755 index 0000000..6811e89 --- /dev/null +++ b/completablefuture/scripts/compile-broken.sh @@ -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" diff --git a/completablefuture/scripts/run-all.sh b/completablefuture/scripts/run-all.sh new file mode 100755 index 0000000..21fc0ae --- /dev/null +++ b/completablefuture/scripts/run-all.sh @@ -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 diff --git a/completablefuture/src/broken/StructuredScopeWithoutPreview.java b/completablefuture/src/broken/StructuredScopeWithoutPreview.java new file mode 100644 index 0000000..3ed38ea --- /dev/null +++ b/completablefuture/src/broken/StructuredScopeWithoutPreview.java @@ -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(); + } + } +} diff --git a/completablefuture/src/main/java/com/ankurm/completablefuture/AllOfAnyOfDemo.java b/completablefuture/src/main/java/com/ankurm/completablefuture/AllOfAnyOfDemo.java new file mode 100644 index 0000000..f40d25a --- /dev/null +++ b/completablefuture/src/main/java/com/ankurm/completablefuture/AllOfAnyOfDemo.java @@ -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 after(long ms, String value, ExecutorService pool) { + return CompletableFuture.supplyAsync(() -> { + sleep(ms); + return value; + }, pool); + } + + static CompletableFuture 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 allOrFailFast(List> futures) { + CompletableFuture 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 CompletableFuture firstSuccess(List> futures) { + CompletableFuture result = new CompletableFuture<>(); + AtomicInteger failures = new AtomicInteger(); + for (CompletableFuture 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 - you collect results yourself"); + CompletableFuture a = after(50, "a", pool); + CompletableFuture b = after(80, "b", pool); + CompletableFuture c = after(30, "c", pool); + CompletableFuture> 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 early = failAfter(50, pool); + CompletableFuture 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 early2 = failAfter(50, pool); + CompletableFuture 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 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); + } + } +} diff --git a/completablefuture/src/main/java/com/ankurm/completablefuture/ExceptionHandlingDemo.java b/completablefuture/src/main/java/com/ankurm/completablefuture/ExceptionHandlingDemo.java new file mode 100644 index 0000000..8255d01 --- /dev/null +++ b/completablefuture/src/main/java/com/ankurm/completablefuture/ExceptionHandlingDemo.java @@ -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. + * + *

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 failing() { + return CompletableFuture.supplyAsync(() -> { + throw new IllegalStateException("boom"); + }); + } + + static CompletableFuture failedDirectly() { + CompletableFuture 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 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 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); + } +} diff --git a/completablefuture/src/main/java/com/ankurm/completablefuture/JoinHelpsDemo.java b/completablefuture/src/main/java/com/ankurm/completablefuture/JoinHelpsDemo.java new file mode 100644 index 0000000..b1b2fc8 --- /dev/null +++ b/completablefuture/src/main/java/com/ankurm/completablefuture/JoinHelpsDemo.java @@ -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. + * + *

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 sample = new AtomicReference<>(); + + int ranOnMainWhenJoining = 0; + for (int i = 0; i < trials; i++) { + CountDownLatch gate = new CountDownLatch(1); + AtomicReference ranOn = new AtomicReference<>(); + CompletableFuture source = CompletableFuture.supplyAsync(() -> { + await(gate); + return "x"; + }); + CompletableFuture 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 ranOn = new AtomicReference<>(); + CompletableFuture 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); + } + } + } +} diff --git a/completablefuture/src/main/java/com/ankurm/completablefuture/ThenApplyVsComposeDemo.java b/completablefuture/src/main/java/com/ankurm/completablefuture/ThenApplyVsComposeDemo.java new file mode 100644 index 0000000..5488511 --- /dev/null +++ b/completablefuture/src/main/java/com/ankurm/completablefuture/ThenApplyVsComposeDemo.java @@ -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. + * + *

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 fetchUser(long id, ExecutorService io) { + return CompletableFuture.supplyAsync(() -> { + sleep(100); + return new User(id, "ankur"); + }, io); + } + + static CompletableFuture fetchLastOrder(User user, ExecutorService io) { + return CompletableFuture.supplyAsync(() -> { + sleep(150); + return new Order(user.id(), "laptop"); + }, io); + } + + static CompletableFuture 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> 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 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 = fetchUser(1, io); + CompletableFuture 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))); + } + } +} diff --git a/completablefuture/src/main/java/com/ankurm/completablefuture/TimeoutDemo.java b/completablefuture/src/main/java/com/ankurm/completablefuture/TimeoutDemo.java new file mode 100644 index 0000000..a8249da --- /dev/null +++ b/completablefuture/src/main/java/com/ankurm/completablefuture/TimeoutDemo.java @@ -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 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 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 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()); + } + } +} diff --git a/completablefuture/src/main/java/com/ankurm/completablefuture/Util.java b/completablefuture/src/main/java/com/ankurm/completablefuture/Util.java new file mode 100644 index 0000000..710d32d --- /dev/null +++ b/completablefuture/src/main/java/com/ankurm/completablefuture/Util.java @@ -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 timed(String label, Supplier> 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; + } +} diff --git a/completablefuture/src/main/java/com/ankurm/completablefuture/VirtualThreadsBenchmark.java b/completablefuture/src/main/java/com/ankurm/completablefuture/VirtualThreadsBenchmark.java new file mode 100644 index 0000000..cd60478 --- /dev/null +++ b/completablefuture/src/main/java/com/ankurm/completablefuture/VirtualThreadsBenchmark.java @@ -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. + * + *

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 body, Executor executor) { + long t0 = System.nanoTime(); + List> 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)); + } + } +} diff --git a/completablefuture/src/main/java/com/ankurm/completablefuture/WhichThreadDemo.java b/completablefuture/src/main/java/com/ankurm/completablefuture/WhichThreadDemo.java new file mode 100644 index 0000000..41ea1da --- /dev/null +++ b/completablefuture/src/main/java/com/ankurm/completablefuture/WhichThreadDemo.java @@ -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? + * + *

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). + * + *

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 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 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 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")); + } + } +} diff --git a/completablefuture/src/test/java/com/ankurm/completablefuture/CompletableFutureContractTest.java b/completablefuture/src/test/java/com/ankurm/completablefuture/CompletableFutureContractTest.java new file mode 100644 index 0000000..1f81c59 --- /dev/null +++ b/completablefuture/src/test/java/com/ankurm/completablefuture/CompletableFutureContractTest.java @@ -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> nested = + CompletableFuture.completedFuture(1).thenApply(x -> CompletableFuture.completedFuture(x + 1)); + assertInstanceOf(CompletableFuture.class, nested.join()); + } + + @Test + void thenComposeFlattensIt() { + CompletableFuture 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 x = CompletableFuture.supplyAsync(() -> { sleep(150); return 1; }, io); + CompletableFuture 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 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 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 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.supplyAsync(() -> { throw new IllegalStateException("boom"); }) + .handle((v, ex) -> ex).join(); + assertInstanceOf(CompletionException.class, seen); + assertInstanceOf(IllegalStateException.class, seen.getCause()); + } + + @Test + void completeExceptionallyIsSeenRawOnTheSameStageAndWrappedDownstream() { + CompletableFuture 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 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 f = CompletableFuture.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 f = CompletableFuture.failedFuture(new IllegalStateException("boom")) + .whenComplete((v, ex) -> observed.set(ex != null)); + assertTrue(observed.get()); + assertTrue(f.isCompletedExceptionally()); + } + + @Test + void handleAndExceptionallyRecover() { + CompletableFuture 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.failedFuture(new IllegalStateException("boom")) + .exceptionallyCompose(ex -> CompletableFuture.completedFuture(99)).join(); + assertEquals(99, v); + } + + // ---- timeouts and cancellation ---------------------------------------------------------- + + @Test + void orTimeoutFailsTheFutureWithTimeoutException() { + CompletableFuture f = new CompletableFuture().orTimeout(50, TimeUnit.MILLISECONDS); + CompletionException ce = assertThrows(CompletionException.class, f::join); + assertInstanceOf(TimeoutException.class, ce.getCause()); + } + + @Test + void completeOnTimeoutSuppliesTheFallback() { + String v = new CompletableFuture().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 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 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 early = CompletableFuture.supplyAsync(() -> { + sleep(30); + throw new IllegalStateException("early"); + }, pool); + AtomicBoolean slowDone = new AtomicBoolean(); + CompletableFuture 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 early = AllOfAnyOfDemo.failAfter(30, pool); + AtomicBoolean slowDone = new AtomicBoolean(); + CompletableFuture 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 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 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> 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"); + } + } +} diff --git a/pom.xml b/pom.xml index b7b9289..a3bc0ef 100644 --- a/pom.xml +++ b/pom.xml @@ -43,6 +43,7 @@ bufferedreader parallel-streams random + completablefuture