Futures, Promises & async

Three states, settled once

A Future is a tiny state machine with exactly three states, and it moves through them once:

• PENDING — the default. The work is in flight; the box is empty. Anyone who asks for the value now has to wait.
• COMPLETED — the work finished and the value is in the box. Reading it is instant from now on, forever, for everyone.
• FAILED — the work threw. The box holds an error instead of a value, and reading it re-throws that error at you.

The word for "reached COMPLETED or FAILED" is settled. Settling is a one-way door: a Future never goes back to pending, and never settles twice. That immutability is what makes Futures safe to share — ten different pieces of code can hold the same Future and they all see the same single result.

Future vs Promise: the read side and the write side

These two words get used interchangeably, but classically they name the two ends of the same box. The Future is the read side — what the caller holds, the thing you wait on or attach callbacks to; it has no way to set a value. The Promise is the write side — what the producer holds, the thing with complete(value) and completeExceptionally(error) on it. Whoever is doing the work fulfils the promise; whoever is waiting reads the future.

Languages split this differently. C++ is explicit: std::promise (producer) hands out a std::future (consumer). Java's CompletableFuture merges both roles into one class, which is why it can both be awaited and be completed by hand. JavaScript's Promise is confusingly named — it's actually the read side; the write side is the resolve/reject pair passed into the constructor. Same mechanism every time: one end writes once, the other end reads.

The whole point is overlap

Here's the mistake everybody makes first. You submit three tasks, and then immediately call get() on each one inside the loop:

// ❌ The classic beginner mistake — serial code with extra steps
for (String id : ids) {
    Future<Price> f = executor.submit(() -> fetchPrice(id)); // starts...
    Price p = f.get();          // ...and we immediately stand there waiting
    total += p.amount();        // 3 × 300 ms = 900 ms
}

// ✅ Submit everything FIRST, then collect — the waits overlap
List<Future<Price>> futures = new ArrayList<>();
for (String id : ids) {
    futures.add(executor.submit(() -> fetchPrice(id))); // all in flight now
}
for (Future<Price> f : futures) {
    total += f.get(2, TimeUnit.SECONDS).amount();       // ≈ 300 ms in total
}

Both versions use Futures. Only the second one is faster. get() blocks — it parks the calling thread until the Future settles — so calling it right after you submit hands back all the benefit you just bought. The gain isn't the Future object; it's the overlap you create in the gap between submitting and reading. Three 300 ms calls that wait at the same time finish in roughly 300 ms, because you're waiting on the network, not on the CPU, and waiting is something you can do in parallel for free.

Callbacks and chaining: say what happens next

Blocking on get() is the crude way to read a Future. The good way is to attach a continuation: tell the Future what to run once it settles, and walk away without holding a thread hostage. thenApply (Java), .then (JavaScript) and await (Python, C#, JS) all do this. Chaining then gives you two composition moves:

• Transform / sequence — thenApply(fn) maps the value; thenCompose(fn) runs another Future afterwards (JS: returning a promise from .then). This is genuinely dependent work — call B needs call A's result — so it can't overlap, and the total time is the sum. That's the 🔗 then chain chip in the prototype.
• Combine / fan-in — CompletableFuture.allOf(a, b, c) (Java), Promise.all([a, b, c]) (JS), asyncio.gather(...) (Python), a sync.WaitGroup or a channel drain (Go). These are independent calls, so they overlap and the total is the slowest one, not the sum.

Errors travel down the chain

When a Future fails, the error doesn't get thrown where you attached the callback — that code already returned long ago. Instead the failure propagates down the chain: every thenApply after it is skipped, and the error keeps sliding until something catches it (exceptionally / handle in Java, .catch in JS, try/except around await in Python). If nothing catches it, the error is stored inside the last Future and silently disappears — no stack trace, no crash, just a value that never shows up. Node calls this an unhandled rejection; Java calls it a Future nobody joined. Both are nasty to debug.

Timeouts and cancellation

Never wait forever on something that talks to a network. Every Future API gives you a bounded wait — f.get(2, TimeUnit.SECONDS), asyncio.wait_for(coro, timeout=2), future.wait_for(2s) in C++, select with context.WithTimeout in Go. And when you no longer need a result — the user closed the page, a sibling call already failed — cancel it: future.cancel(true), task.cancel(), AbortController, a cancelled context.Context. Cancellation is cooperative almost everywhere: it sets a flag or fires an interrupt, and the task has to notice and stop. A timeout without a cancel just means you stopped waiting while the work keeps burning resources.

Callback hell vs async/await

Early callback-based code nested every step inside the previous step's handler, and three or four levels in it became an unreadable staircase — callback hell. async/await fixes the reading problem: var price = await fetchPrice(); looks like a plain blocking line, but the compiler chops the function in half at that await, returns control to the runtime, and resumes the rest when the Future settles. It's the same Futures and callbacks underneath; you just get to write it top to bottom, with normal try/catch and normal loops.

How the four languages spell it

• Java — Future<T> is the old, blocking-only interface (get(), cancel()); CompletableFuture<T> adds thenApply / thenCompose / allOf / exceptionally. Since Java 21, virtual threads offer an alternative: write plain blocking code and let the JVM park the cheap virtual thread instead of an OS thread.
• Python — asyncio with async def, await, asyncio.gather(...) and asyncio.wait_for(...), all on a single-threaded event loop; concurrent.futures gives thread-pool Future objects for the blocking style.
• C++ — std::future / std::promise / std::async, plus wait_for for timeouts. get() moves the value out and re-throws any stored exception; C++20 coroutines add co_await on top.
• Go — has no Future type on purpose. You launch a goroutine and give it a channel; the channel is the future, and receiving from it is the get(). sync.WaitGroup is your allOf, and context.Context carries the timeout and cancellation.

Reach for Futures / async when...

• The work is I/O-bound — network calls, database queries, file reads, other services. The thread is waiting, not computing, and waiting is exactly what you can overlap for free.
• You have several independent slow calls — a page that needs price and stock and reviews. Fire them all, then combine with allOf / Promise.all / gather. Total time becomes the slowest call, not the sum.
• You need to stay responsive — a UI that must not freeze, or a server that must keep accepting connections while requests are in flight.
• Concurrency is high but each unit is cheap — thousands of open sockets. One event loop holds them all; thousands of blocked threads would not fit.

Skip it when...

• The work is CPU-bound — hashing, image resizing, big matrix maths. Async doesn't make the CPU faster; you need real threads or processes for that.
• The calls genuinely depend on each other — if B needs A's result, chaining buys you nothing over straight-line code except complexity. Only independent work overlaps.
• There's just one quick call and nothing else to do — a plain synchronous call is simpler, easier to debug, and has a readable stack trace.
• Your runtime already gives you cheap blocking — with Java 21 virtual threads or Go goroutines you can often write plain blocking code and let the runtime park it, keeping the readability without the callback machinery.