How does CompletableFuture work in Java and how does it relate to virtual threads?

CompletableFuture<T> (Java 8) provides composable asynchronous computation pipelines. It lets you chain transformations (thenApply), combinations (thenCombine), and error handlers (exceptionally) without blocking threads.

// Basic async computation
CompletableFuture future = CompletableFuture
    .supplyAsync(() -> fetchUserName(userId))     // runs in ForkJoinPool
    .thenApply(String::toUpperCase)               // transform result
    .thenApply(name -> "Hello, " + name);

System.out.println(future.join()); // blocks calling thread until done

// Combining two independent futures
CompletableFuture   userFuture  = CompletableFuture.supplyAsync(() -> fetchUser(id));
CompletableFuture  orderFuture = CompletableFuture.supplyAsync(() -> fetchOrder(id));

CompletableFuture result = userFuture
    .thenCombine(orderFuture,
        (user, order) -> user.name() + " ordered " + order.item());

// Error handling
future.exceptionally(ex -> "Default value on error: " + ex.getMessage())
      .thenAccept(System.out::println);

// Run all, collect results
List> futures = ids.stream()
    .map(id -> CompletableFuture.supplyAsync(() -> fetch(id)))
    .toList();
CompletableFuture.allOf(futures.toArray(new CompletableFuture[0]))
    .thenApply(v -> futures.stream().map(CompletableFuture::join).toList())
    .join();

// With virtual threads (Java 21): use simple blocking code instead
// StructuredTaskScope is the recommended replacement for CompletableFuture
// when running on virtual threads — simpler and handles cancellation

With Java 21 virtual threads, the async/reactive style of CompletableFuture is less necessary for I/O-bound work — you can write simple blocking code on virtual threads and achieve the same throughput. However, CompletableFuture remains useful for CPU-bound parallel pipelines and for code that must integrate with existing async APIs.

Invest now in Acorns!!! 🚀
Join Acorns and get your $5 bonus!

Acorns is a micro-investing app that automatically invests your "spare change" from daily purchases into diversified, expert-built portfolios of ETFs. It is designed for beginners, allowing you to start investing with as little as $5. The service automates saving and investing. Disclosure: I may receive a referral bonus.

Invest now!!! Get Free equity stock (US, UK only)!

Use Robinhood app to invest in stocks. It is safe and secure. Use the Referral link to claim your free stock when you sign up!.

The Robinhood app makes it easy to trade stocks, crypto and more.

Webull! Receive free stock by signing up using the link: Webull signup.