Why does calling cancel() on a CompletableFuture often fail to actually stop the running work or propagate through a chain, and how should cancellation be designed instead?

## What cancel() does — and doesn't — do `CompletableFuture` implements `Future`, so it has `cancel(boolean mayInterruptIfRunning)`. But its behavior differs sharply from the classic `FutureTask`: - It **completes the future exceptionally** with a `CancellationException`. - It **ignores `mayInterruptIfRunning`** entirely. There is *no* thread reference inside a CompletableFuture, so it **cannot** interrupt the thread running your `supplyAsync` body. (The JDK docs explicitly note this.) Consequence: if you do ```java var f = CompletableFuture.supplyAsync(this::expensiveBlockingCall, pool); f.cancel(true); ``` the future `f` immediately reports cancelled/completed-exceptionally, **but `expensiveBlockingCall` keeps running** on the pool thread until it finishes naturally. You've cancelled the *handle*, not the *work*. The thread stays occupied, which can defeat the very point of cancelling (freeing resources / stopping a timeout-exceeded request). ## Cancellation propagates DOWN, not UP A CompletableFuture chain is a one-way dependency graph: downstream stages consume upstream results. When an upstream stage completes exceptionally (including by cancellation), that exceptional outcome flows **downstream** — dependent stages are skipped and see a `CompletionException`/`CancellationException`. But the reverse is **not** true. If you cancel a *downstream* stage: ```java var source = CompletableFuture.supplyAsync(this::loadHuge, pool); var mapped = source.thenApply(this::transform); mapped.cancel(true); // cancels 'mapped' only ``` `source` (the expensive producer) is **unaffected** — `loadHuge` runs to completion. Cancellation does not travel *back* up to producers. This is the "failure to propagate cancellation through a chain" pitfall: people cancel the tail of the chain and assume the head stops. It doesn't. ## Why it's built this way CompletableFuture is a *completion* abstraction: it models "a value that will arrive," decoupled from *how* it's computed or *which* thread computes it. Many futures aren't backed by a thread at all (they may be completed by an I/O callback, an event, or `complete()` called externally). There's simply no universal thread to interrupt — so the framework offers completion semantics, not execution control. ## How to design cancellation properly 1. **Cooperative cancellation in the task.** The running work must *opt in* to stopping: periodically check `Thread.interrupted()` (if you arrange interruption) or a shared `volatile boolean`/`AtomicBoolean cancelled` flag, and abort early when set. No flag-checking ⇒ no early stop. 2. **Cancel the right (upstream) future.** Keep a reference to the **source** future (and any expensive intermediates) and cancel *those*, not just the tail. Or cancel several stages explicitly. 3. **Thread a cancellation token.** Pass a token (e.g. an `AtomicBoolean`, or a richer `CancellationToken`-like object) through the stages so each can check it and so cancelling one place signals all. 4. **Make blocking calls interruptible.** If a stage blocks (I/O, lock), run it where you can interrupt the carrier and have the blocking API respond to interruption (e.g. `lockInterruptibly`, interruptible channels), then translate the interrupt into early return. 5. **Release resources on cancellation.** Attach `whenComplete((v, ex) -> { if (ex instanceof CancellationException) cleanup(); })` to free connections/handles when a stage is cancelled. 6. **Timeouts.** `orTimeout`/`completeOnTimeout` (Java 9+) complete the future on time but, like cancel, *don't stop the underlying work* — combine with cooperative cancellation if the work must actually halt. ## Contrast with structured concurrency / virtual threads Newer models (Java's `StructuredTaskScope`, virtual threads) make cancellation/interruption first-class: cancelling a scope interrupts its subtasks. If you need real, propagating cancellation, those abstractions are often a better fit than hand-rolling tokens over CompletableFuture chains. ## Mental model `cancel()` = "mark *this* future as cancelled and tell *downstream* stages." It is **not** "stop the thread" and **not** "cancel my producers." Real cancellation = cooperative checks in the work + cancelling the upstream source + (optionally) interruption and cleanup.