Can Virtual Threads in Java 21 Replace CompletableFuture for Asynchronous Programming?

Why CompletableFuture became popular

Platform (OS) threads are expensive: each consumes about 1 MB of stack memory, so a machine with 8 GB RAM can only host a few thousand threads. To avoid thread‑pool exhaustion, developers turned to CompletableFuture to turn blocking operations into non‑blocking callback chains.

// Forced to write this because threads are scarce
CompletableFuture.supplyAsync(() -> queryUser(userId))
    .thenApply(user -> queryOrders(user))
    .thenApply(orders -> calcTotal(orders))
    .thenAccept(total -> sendResponse(total));

The code works but is hard to read and debug: nested callbacks break the call stack and scatter exception handling across many thenApply and exceptionally calls.

What virtual threads change

Virtual threads cost only a few kilobytes and can be scheduled in the hundreds of thousands on a single machine. When a virtual thread blocks on I/O, the underlying carrier thread is released and reused, and the virtual thread is automatically remounted after the I/O completes.

// With virtual threads, write synchronous‑style code
Thread.startVirtualThread(() -> {
    User user = queryUser(userId); // blocking is fine
    List<Order> orders = queryOrders(user);
    BigDecimal total = calcTotal(orders);
    sendResponse(total);
});

This eliminates callback hell, produces a clear stack trace, and simplifies debugging.

Limits of replacing CompletableFuture

CompletableFuture is more than an async‑execution tool; it is a declarative task‑orchestration API. Features such as parallel composition, race‑condition handling, and declarative timeout or fallback logic are expressed concisely with methods like allOf, anyOf, exceptionally, and orTimeout. Virtual threads alone cannot express these patterns as elegantly.

// Parallel composition with CompletableFuture
CompletableFuture<User> userFuture = CompletableFuture.supplyAsync(() -> queryUser(id));
CompletableFuture<List<Order>> orderFuture = CompletableFuture.supplyAsync(() -> queryOrders(id));
CompletableFuture<Integer> pointsFuture = CompletableFuture.supplyAsync(() -> queryPoints(id));
CompletableFuture.allOf(userFuture, orderFuture, pointsFuture).join();
UserProfile profile = merge(userFuture.join(), orderFuture.join(), pointsFuture.join());

Structured concurrency via StructuredTaskScope can achieve similar parallelism, but the API is still in preview, may change, and enforces a stricter "all‑tasks‑must‑finish‑inside‑scope" model, limiting flexibility compared to CompletableFuture.

try (var scope = new StructuredTaskScope.ShutdownOnFailure()) {
    var userTask = scope.fork(() -> queryUser(id));
    var orderTask = scope.fork(() -> queryOrders(id));
    var pointsTask = scope.fork(() -> queryPoints(id));
    scope.join();
    scope.throwIfFailed();
    UserProfile profile = merge(userTask.get(), orderTask.get(), pointsTask.get());
}

Because StructuredTaskScope does not support chaining methods like thenCompose, it cannot replace the full composability of CompletableFuture.

When to use which

For simple I/O‑bound work (database queries, HTTP calls, file reads), prefer virtual threads with straightforward synchronous code – the code is concise, the stack trace is natural, and debugging is easy.

For complex multi‑task orchestration (parallel joins, race conditions, fallback strategies, declarative timeouts), keep using CompletableFuture as it provides a richer, less error‑prone API.

Mixing both is also viable: run CompletableFuture pipelines on a virtual‑thread executor.

// Combine virtual threads with CompletableFuture
ExecutorService executor = Executors.newVirtualThreadPerTaskExecutor();
CompletableFuture<User> userFuture = CompletableFuture.supplyAsync(() -> queryUser(id), executor);
CompletableFuture<List<Order>> orderFuture = CompletableFuture.supplyAsync(() -> queryOrders(id), executor);
CompletableFuture.allOf(userFuture, orderFuture).join();

This approach leverages the lightweight nature of virtual threads while retaining the expressive power of CompletableFuture for task composition.