What are the exact semantics of cancel() on a CompletableFuture, and what do obtrudeValue/obtrudeException do that you should rarely need?

### Background: a CompletableFuture is a result holder, not a task A key mental model: a `CompletableFuture` is fundamentally a **single-assignment cell** for a result — it is **not** intrinsically tied to a thread or a running computation. Even `supplyAsync(task)` returns a future that is conceptually "a slot the task will fill"; the future doesn't *own* the task's thread. This explains every surprising thing below. ### cancel(mayInterruptIfRunning) ```java boolean cancel(boolean mayInterruptIfRunning); ``` From the `Future` interface, but CompletableFuture's implementation is special: - If the future is **already completed**, returns `false`, no effect. - If **incomplete**, it completes the future **exceptionally with a `CancellationException`** and returns `true`. After this `isCancelled()` and `isCompletedExceptionally()` are both `true`. - The **`mayInterruptIfRunning` flag has no effect** — the Javadoc states it because a CompletableFuture is not associated with a thread it could interrupt. So you cannot use `cancel(true)` to interrupt the `supplyAsync` worker. **Consequence:** "cancel" really means "settle this future as cancelled". The underlying computation (if any) is **not** stopped — it runs to completion, and its result is discarded because the future is already settled (first-wins). ### Propagation: downstream yes, upstream no Cancelling a future fails its **dependents** with a `CancellationException` (a `thenApply` after it won't run). But it does **not** propagate **upstream**: cancelling `b` in `a.thenApply(f) == b` does not cancel `a`. Each stage is its own cell. This asymmetry trips people up who expect cancellation to unwind the whole chain. ### So how do you actually stop work? You need a handle on the real task: submit a `Runnable`/`Callable` to an `ExecutorService` and cancel **that** `Future` with interruption, or pass a cancellation token your task polls, or use structured concurrency. The CompletableFuture's `cancel` alone only abandons the result. ### obtrudeValue and obtrudeException — the invariant-breakers ```java void obtrudeValue(T value); void obtrudeException(Throwable ex); ``` Normally a future is **write-once**: the first `complete`/`completeExceptionally`/`cancel` wins and the result is immutable thereafter. `obtrudeValue`/`obtrudeException` **bypass that rule** — they **forcibly overwrite** the result **even if the future is already completed**, and reset its state to the new value/exception. Unlike `complete`, they return `void` (no first-wins check) and always take effect. Why do they exist? The Javadoc says explicitly: for **error recovery** and **testing** — situations where you knowingly want to reset a stuck/wrong result. Why you should almost never use them in production: - They **break the single-assignment invariant** that all composition logic assumes. Dependent stages may have **already** fired on the old result; obtruding doesn't un-fire them, so you get an inconsistent view. - They introduce **races with no winner-determinism** — there's no boolean to tell you whether you clobbered a value. - They make reasoning about the future impossible: "settled" no longer means "final." The pragmatic principal-level stance: treat `obtrude*` as a **test-only / last-resort recovery** tool, fence it off, and never expose a future you obtrude on to general composition. ### Worked example ```java CompletableFuture<Integer> cf = CompletableFuture.supplyAsync(() -> slowCompute()); cf.cancel(true); // completes cf with CancellationException; slowCompute keeps running cf.isCancelled(); // true // cf.get() now throws CancellationException; slowCompute's eventual result is dropped CompletableFuture<String> g = new CompletableFuture<>(); g.complete("first"); g.obtrudeValue("second"); // forcibly overwrites — g.join() now returns "second" (invariant broken) ``` ### Putting it together for a senior/principal answer The through-line: a CompletableFuture is a **promise/result cell**, decoupled from the work that fills it. `cancel` settles the cell (no interruption); timeouts settle the cell (no interruption); only an `obtrude*` call can rewrite an already-settled cell — and doing so breaks the guarantees everyone else builds on. Real cancellation of work lives at the task/executor layer, not on the future.