Skip to content
Tutorials Center
My learning

Topics

Lesson 137 of 201 ยท Concurrency

Virtual Threads and Structured Concurrency

Learn Java virtual threads - how they differ from platform threads, newVirtualThreadPerTaskExecutor, pinning, scoped values, and structured concurrency with StructuredTaskScope.

For most of Java's history, every Thread was a thin wrapper around an operating-system thread. Those platform threads are expensive: each reserves a large stack, and an OS juggles a few thousand of them comfortably, not a million. A server that handled one request per thread could therefore serve only a few thousand requests at once, even when those threads spent 99% of their time waiting for a database or another service. The workaround was asynchronous code (CompletableFuture, reactive libraries), which scales but is harder to write, read and debug.

Virtual threads (final in Java 21) remove that trade-off. They're real java.lang.Thread objects, but the JVM, not the OS, schedules them, and they cost about as much as a small object. You can start a million of them. When one blocks on I/O, a lock or sleep, the JVM parks it and uses the underlying OS thread for another virtual thread. You write simple blocking code, one thread per task, and get the scalability of async code.

This lesson shows how to create and use virtual threads, where they help and where they don't, the pinning caveat, scoped values (final in Java 25) and structured concurrency (a preview API in Java 25).

Platform threads vs virtual threads

Platform thread Virtual thread
Backed by one OS thread, for its whole life any carrier thread, borrowed while running
Memory a fixed stack reservation (often around 1 MB) a few hundred bytes plus a stack that grows on the heap
Practical count thousands millions
Scheduled by the operating system the JVM (a ForkJoinPool of carrier threads)
Daemon your choice always daemon
Priority adjustable always NORM_PRIORITY
Good for CPU-heavy work, long-lived background threads tasks that spend most of their time waiting

The JVM runs virtual threads on a small pool of platform threads called carriers, by default one per CPU core. A virtual thread is mounted on a carrier while it runs. When it blocks in a JDK operation (socket read, Thread.sleep, BlockingQueue.take, ReentrantLock.lock, and since Java 24 also synchronized), the JVM saves its stack to the heap and unmounts it, freeing the carrier for another virtual thread. When the operation can continue, the virtual thread is mounted again, maybe on a different carrier.

Creating virtual threads

The Thread API is unchanged; there are just new ways to construct threads.

Java Starting virtual threads

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Virtual threads are always daemon threads, so the JVM doesn't wait for them on exit: if main returns without joining, unfinished virtual threads simply stop. In practice you'll rarely create them one by one. The usual tool is an executor.

One virtual thread per task

Executors.newVirtualThreadPerTaskExecutor() starts a new virtual thread for every task. There's no pool and no queue: virtual threads are too cheap to pool. Here are 10,000 tasks that each "wait for a remote call" for 100 ms, compared with a classic pool of 50 platform threads running 500 such tasks.

Java 10,000 blocking tasks

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

The fixed pool needs ten rounds of 100 ms for its 500 tasks, about one second. The virtual-thread executor runs twenty times more tasks in a few hundred milliseconds, because all 10,000 sleep at the same time; the exact figure depends on the machine. Our sandbox has a single CPU core, so all those threads share one carrier, and it still works. Sleeping virtual threads don't occupy a carrier.

What virtual threads don't do

Virtual threads make waiting cheap. They don't make computing faster. A CPU-bound task (hashing, image processing, number crunching) keeps its carrier busy the whole time, and you still have only as many carriers as cores. For CPU-heavy work, use a fixed pool sized to the cores, fork/join or parallel streams. Virtual threads shine for servers, crawlers, and batch jobs dominated by network and database calls.

Rules for using virtual threads well

Don't pool them. A pool exists to reuse expensive threads. Virtual threads aren't expensive, so create one per task and let it die.

Limit resources, not threads. With a pool of 20 threads, you implicitly allowed at most 20 concurrent database calls. With virtual threads that limit is gone, and 10,000 requests can hit your database at once. Use a Semaphore to cap access to the scarce resource:

Java Capping concurrency with a Semaphore

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

200 virtual threads exist at once, but never more than 10 queries run at the same time. The waiting threads cost almost nothing while they're parked on the semaphore.

Be careful with ThreadLocal. Virtual threads support thread-locals, but with a million threads, a 1 MB cached object per thread is a million megabytes. Thread-locals used as caches for expensive objects (formatters, buffers) assumed a few long-lived pool threads. Share immutable objects instead, and use scoped values for passing context.

Keep using the same APIs. JDBC drivers, HttpClient, sockets, BlockingQueue and locks all work. Frameworks enable virtual threads with a setting (for example, spring.threads.virtual.enabled=true in Spring Boot, covered in Advanced Java).

Pinning

Sometimes a virtual thread can't unmount while it blocks; it's pinned to its carrier, and that carrier is stuck until the operation finishes. With only a few carriers, a handful of pinned threads can stall the whole application.

  • Java 21โ€“23: a virtual thread blocking inside a synchronized block or method was pinned. The standard advice was to replace synchronized with ReentrantLock around blocking calls.
  • Java 24 and later (JEP 491): synchronized no longer pins. Virtual threads can block inside it, and Object.wait() releases the carrier too.
  • Still pinned today: blocking while a native method or foreign function is on the stack, and (rarely) during class initialization. JDK Flight Recorder reports long pins with the jdk.VirtualThreadPinned event.

The next program would have been painfully slow on Java 21 with one carrier: each sleeping thread would have held the only carrier while inside synchronized. On Java 25 it's fast.

Java synchronized no longer pins (Java 24+)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Each account has its own lock, so the threads don't compete with each other; they only sleep. Because they unmount while sleeping, all 1,000 sleeps overlap.

Scoped values

A scoped value (java.lang.ScopedValue, final in Java 25) passes data down a call chain without adding parameters to every method, like a ThreadLocal but safer and cheaper:

  • The value is bound for a scope with ScopedValue.where(KEY, value).run(...) (or .call(...) to return a result) and automatically unbound when the scope ends. There's no set and no forgotten remove().
  • It's immutable inside the scope. A nested scope can rebind it for its own callees only.
  • Child threads created with structured concurrency inherit it at almost no cost.

Typical uses are request context in servers: the current user, a transaction, a trace ID.

Java Passing context with ScopedValue

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

loadDashboard and log take no parameters, yet each request's log lines carry the right user and trace ID. The nested where(USER, "system") affects only the code inside it; the next line sees "ana" again. Outside every scope, isBound() is false, orElse supplies a default, and get() throws.

Structured concurrency (preview)

When a task splits into concurrent subtasks, plain executors don't express the relationship: if one subtask fails, the others keep running; if the parent is cancelled, the children don't know. Structured concurrency treats a group of subtasks as one unit with a clear scope, the way a try block structures error handling: subtasks start inside the block, and the block doesn't exit until all of them are done.

StructuredTaskScope is still a preview API in Java 25 (its fifth preview, JEP 505, with a redesigned API compared with Java 21โ€“24). Preview code needs --enable-preview to compile and run, so the code below is read-only, and details may change before it becomes final.

Java
import java.util.concurrent.StructuredTaskScope;
import java.util.concurrent.StructuredTaskScope.Subtask;

record Page(User user, List<Order> orders) {}

Page loadPage(int userId) throws InterruptedException {
    try (var scope = StructuredTaskScope.open()) {            // default: all must succeed
        Subtask<User> user = scope.fork(() -> findUser(userId));       // each fork runs
        Subtask<List<Order>> orders = scope.fork(() -> findOrders(userId)); // in a new virtual thread

        scope.join();          // waits for both; if one fails, the other is cancelled
                               // and join() throws StructuredTaskScope.FailedException
        return new Page(user.get(), orders.get());
    }                          // leaving the block guarantees no subtask is still running
}

Other policies are chosen with a joiner. For example, ask three mirrors and take the first answer:

Java
try (var scope = StructuredTaskScope.open(
        StructuredTaskScope.Joiner.<String>anySuccessfulResultOrThrow())) {
    for (String mirror : List.of("eu", "us", "asia")) {
        scope.fork(() -> download(mirror));
    }
    return scope.join();       // first success; the slower downloads are cancelled
}
Terminal
# compiling and running preview code yourself
java --enable-preview Main.java

What structured concurrency gives you: no leaked threads after the block, failures that cancel siblings automatically, cancellation (interrupting the parent) that reaches every child, scoped values inherited by every subtask, and thread dumps that show the parent-child tree. Until it's final, you can get much of the same effect with newVirtualThreadPerTaskExecutor() in try-with-resources plus careful error handling.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. A program runs 10,000 tasks that each compute SHA-256 hashes in a tight loop for 1 second. What do virtual threads gain over a fixed pool sized to the CPU cores?

    Virtual threads make blocking cheap. CPU-bound tasks keep their carrier busy, and there are only as many carriers as cores.
  2. 2. Why should you not put virtual threads in a pool such as newFixedThreadPool with a virtual thread factory?

    Create a new virtual thread per task (newVirtualThreadPerTaskExecutor) and cap access to scarce resources with a Semaphore.
  3. 3. What happens to unfinished virtual threads when main returns without joining them?

    Virtual threads are daemon threads, so they don't keep the JVM alive. Join them or close the executor that runs them.
  4. 4. Inside ScopedValue.where(USER, "ana").run(() -> { ScopedValue.where(USER, "sys").run(a); b(); }), what does USER.get() return in b()?

    The nested binding applies only while a runs. When it ends, the outer binding, "ana", is visible again.
  5. 5. Since which Java version does blocking inside a synchronized block no longer pin a virtual thread to its carrier?

    JEP 491 in Java 24 let virtual threads unmount while holding a monitor. In Java 21 to 23, synchronized pinned them.

Summary

  • Virtual threads (Java 21) are cheap Threads scheduled by the JVM on a few carrier threads; blocking unmounts them, so millions can wait at once.
  • Create them with Thread.ofVirtual(), Thread.startVirtualThread or, usually, Executors.newVirtualThreadPerTaskExecutor(), one per task.
  • They speed up I/O-bound concurrency, not CPU-bound work; they're always daemon threads.
  • Don't pool them; limit access to scarce resources with a Semaphore; go easy on ThreadLocal.
  • Since Java 24, synchronized no longer pins; native frames still can.
  • ScopedValue (final in Java 25) passes immutable context down a call chain for a bounded scope.
  • StructuredTaskScope (preview in Java 25) treats subtasks as one unit: fork, join, automatic cancellation, no leaked threads.

Next: Networking Basics, where you'll learn the addresses, ports and protocols that all those waiting threads are usually waiting on.