JAVA-240 · Lesson 8 of 12 · 23 min

Virtual threads

▶ Video coming soon A video version of this lesson is on the way.

Monday, March 6, 2028. Hamza has a question he has been saving. Lesson 6 said a pool of 40 threads might suit OrderDesk's price checks, but the right size depends on how long the supplier takes, which changes from day to day. Is there a way to stop guessing? Ingrid's answer is the biggest change to Java concurrency in twenty years: virtual threads, final since Java 21. With them, the advice for waiting tasks changes from "size a pool carefully" to "start a thread for every task and let Java sort it out".

Why platform threads are scarce

A platform thread is an operating system thread. Each one reserves memory for its stack, and the operating system has to schedule all of them, so a typical server can manage a few thousand before it struggles. For years that limit shaped how Java servers were written. The simple style, one thread per request, stopped working when a server needed to hold ten thousand connections at once, most of them waiting. Programmers moved to thread pools, and then to asynchronous styles like the CompletableFuture chains of lesson 7, which use few threads but are harder to write, read and debug.

What a virtual thread is

A virtual thread is a Java thread that the JVM, rather than the operating system, schedules. The JVM runs virtual threads on a small pool of platform threads called carrier threads, by default about one per core. When a virtual thread blocks, by sleeping, waiting on a lock or a queue, or waiting for a network reply, the JVM unmounts it: it saves the virtual thread's stack in ordinary heap memory and frees the carrier to run another virtual thread. When the virtual thread can continue, it is mounted again on any free carrier and carries on where it stopped.

Two carrier threads drawn as long horizontal lanes. Several small virtual threads, labelled order 1 to order 6, take turns on the lanes: each runs for a short stretch, then is lifted off into a box labelled waiting in heap memory while its network call is in progress, and later comes back on whichever lane is free.
Virtual threads take turns on a few carrier threads, stepping off while they wait

Because a waiting virtual thread uses no carrier and only a small amount of heap, a program can have hundreds of thousands or even millions of them. Code inside a virtual thread is ordinary, blocking, step-by-step Java: Thread.sleep, BlockingQueue.take, a JDBC query, an HTTP call. The JVM turns each blocking call into an unmount behind the scenes. You get the scale of asynchronous code with the plain style of lesson 2.

Creating virtual threads

Virtual threads are instances of the same Thread class, so everything from lesson 2 still applies: start, join, interrupt, states. You create them with a builder from Thread.ofVirtual(), with the shortcut Thread.startVirtualThread(task), or, most often, with an executor that starts a new virtual thread for every task.

Java Example · Main.java
public class Main {
    public static void main(String[] args) throws InterruptedException {
        boolean[] seen = new boolean[3];

        Thread v = Thread.ofVirtual().name("price-check-1").start(() -> {
            Thread me = Thread.currentThread();
            seen[0] = me.isVirtual();
            seen[1] = me.isDaemon();
            seen[2] = me.getName().equals("price-check-1");
        });
        v.join();

        System.out.println("is virtual: " + seen[0]);
        System.out.println("is daemon:  " + seen[1]);
        System.out.println("has its name: " + seen[2]);
        System.out.println("main is virtual: " + Thread.currentThread().isVirtual());
    }
}
Output
is virtual: true
is daemon:  true
has its name: true
main is virtual: false

What this code does

A virtual thread is created and started with Thread.ofVirtual(), given a name, and joined like any other thread. Inside, it reports that it is virtual and that it is a daemon thread, which every virtual thread is. The main thread is an ordinary platform thread.

Every virtual thread is a daemon thread, so it never keeps the JVM alive. A program must therefore wait for its virtual threads, with join or, better, with an executor in a try-with-resources block, before main returns.

A virtual thread per task

Executors.newVirtualThreadPerTaskExecutor() returns an ExecutorService that starts a fresh virtual thread for each submitted task. There is no pool and no size to choose. The program below submits ten thousand tasks that each wait one second, as if checking a price with a slow supplier. With platform threads that would need ten thousand operating system threads or a long queue. With virtual threads it finishes in a little over a second.

Java Example · Main.java
import java.util.concurrent.*;
import java.util.concurrent.atomic.AtomicInteger;

public class Main {
    public static void main(String[] args) {
        AtomicInteger answered = new AtomicInteger();
        long start = System.nanoTime();

        try (ExecutorService executor = Executors.newVirtualThreadPerTaskExecutor()) {
            for (int i = 0; i < 10_000; i++) {
                executor.submit(() -> {
                    Thread.sleep(1_000);
                    answered.incrementAndGet();
                    return null;
                });
            }
        }

        long millis = (System.nanoTime() - start) / 1_000_000;
        System.out.println("price checks answered: " + answered.get());
        System.out.println("finished in under 5 seconds: " + (millis < 5_000));
    }
}
Output
price checks answered: 10000
finished in under 5 seconds: true

What this code does

Ten thousand tasks, each sleeping for one second to stand in for a slow network call, are submitted to a virtual-thread-per-task executor. The try-with-resources block waits for all of them, and the total time is close to one second rather than ten thousand, because sleeping virtual threads give up their carriers. The program prints a yes-or-no comparison rather than the exact time, which varies from run to run.

Lambdas submitted with submit that need to throw a checked exception, such as the InterruptedException from sleep, can be written as a Callable by returning a value, here null. That is why the task ends with return null.

When virtual threads help, and when they do not

Virtual threads make blocking cheap. They do not make code run faster. They help when a program has many tasks that spend most of their time waiting: web requests, database queries, calls to other services, file reads. For CPU-bound work they bring nothing: a calculation keeps its carrier busy until it ends, and there are only as many carriers as cores. For photo resizing or route planning, a fixed pool of about one thread per core is still right.

Where virtual threads fit
SituationGood choiceWhy
Thousands of tasks waiting on networks or databasesnewVirtualThreadPerTaskExecutor()Waiting is nearly free, and the code stays simple
CPU-bound calculationA fixed pool of about one thread per coreVirtual threads add nothing when every task is computing
Limiting load on a service with 5 connectionsVirtual threads plus a Semaphore of 5 permitsLimit the resource, not the threads
A desktop app's single user-interface threadThe toolkit's own thread rulesUser interface frameworks have their own threading model
Code that depends heavily on ThreadLocal cachesReview carefully before switchingOne cache per virtual thread can mean millions of copies

Do not pool virtual threads

Ingrid insists on one habit. Thread pools exist because platform threads are expensive; virtual threads are not, so pooling them makes no sense. Create a new virtual thread for each task, and let it end when the task ends. If you used a pool to limit how many tasks hit a service at once, keep that limit, but express it directly with a Semaphore. A semaphore holds a number of permits: acquire takes one, waiting if none are left, and release gives it back.

Java Example · Main.java
import java.util.concurrent.*;
import java.util.concurrent.atomic.AtomicInteger;

public class Main {
    static final Semaphore supplierConnections = new Semaphore(5);
    static final AtomicInteger inFlight = new AtomicInteger();
    static final AtomicInteger mostAtOnce = new AtomicInteger();

    static int checkPrice(int order) throws InterruptedException {
        supplierConnections.acquire();
        try {
            int now = inFlight.incrementAndGet();
            mostAtOnce.accumulateAndGet(now, Math::max);
            Thread.sleep(50);
            return 1000 + order;
        } finally {
            inFlight.decrementAndGet();
            supplierConnections.release();
        }
    }

    public static void main(String[] args) throws Exception {
        long total = 0;
        try (ExecutorService executor = Executors.newVirtualThreadPerTaskExecutor()) {
            var futures = new java.util.ArrayList<Future<Integer>>();
            for (int order = 1; order <= 60; order++) {
                int o = order;
                futures.add(executor.submit(() -> checkPrice(o)));
            }
            for (Future<Integer> f : futures) total += f.get();
        }
        System.out.println("orders priced: 60, total " + total);
        System.out.println("never more than 5 calls at once: " + (mostAtOnce.get() <= 5));
    }
}
Output
orders priced: 60, total 61830
never more than 5 calls at once: true

What this code does

Sixty orders each get their own virtual thread, but every price check must first acquire one of five permits from a semaphore, so the supplier never sees more than five calls at the same time. The program tracks the largest number of calls in progress with atomic variables and confirms it never passed five. The total is added up from the futures in order, so it is the same on every run.

Pinning and synchronized

In some situations a virtual thread cannot unmount when it blocks, and it holds on to its carrier, which is called pinning. In Java 21, a virtual thread that blocks while inside a synchronized block or method is pinned for as long as it waits. With only a handful of carriers, a few pinned threads waiting on slow calls inside synchronized code can stall every other virtual thread. Java 21 can report pinning with the option -Djdk.tracePinnedThreads=full.

JDK Enhancement Proposal 491 removed that limitation in Java 24: synchronized blocks no longer pin virtual threads, apart from a few rare cases such as calls into native code. On Java 21, the long-term support release this course uses, the usual advice is to avoid blocking for a long time inside synchronized code that virtual threads run, and to use a ReentrantLock there instead, which never pins.

Java Example · Pinning on Java 21
// On Java 21, a virtual thread waiting for the supplier inside synchronized is pinned.
synchronized Price lookUp(String code) {
    return supplier.fetch(code);        // slow network call while holding the monitor
}

// A ReentrantLock lets the virtual thread unmount while it waits.
private final ReentrantLock lock = new ReentrantLock();

Price lookUp(String code) {
    lock.lock();
    try {
        return supplier.fetch(code);
    } finally {
        lock.unlock();
    }
}

What this code does

Both methods allow only one lookup at a time, but on Java 21 the synchronized version pins the virtual thread to its carrier while the network call is in progress. The ReentrantLock version lets the virtual thread step off its carrier while it waits. On Java 24 and later both behave well, though keeping slow calls out of critical sections is still the better design.

ThreadLocal and scoped values

A ThreadLocal gives each thread its own copy of a variable, which older code uses to cache expensive objects such as date formatters or database connections, one per pool thread. With virtual threads there may be a million threads, and a million cached copies. ThreadLocal still works with virtual threads, but caching objects in it no longer saves anything, because each virtual thread is used for one task only.

For passing information down through a task, such as the order number being processed so that every log line can include it, Java 25 adds scoped values, which became a final feature through JDK Enhancement Proposal 506. A ScopedValue is bound to a value for the duration of a call, can be read anywhere inside that call, cannot be changed, and disappears when the call ends. They are cheaper than ThreadLocal and cannot leak. The example below needs Java 25 or later, so it is shown as a listing and not compiled here.

Java Example · Scoped values (Java 25 and later)
static final ScopedValue<String> ORDER = ScopedValue.newInstance();

void handle(String orderId) {
    ScopedValue.where(ORDER, orderId).run(() -> {
        reserveStock();
        log("stock reserved");      // log can read ORDER.get() without a parameter
    });
}

void log(String message) {
    System.out.println("[" + ORDER.get() + "] " + message);
}

What this code does

handle binds the scoped value ORDER to the current order number for the duration of one call. Any method called inside that call, such as log, can read it with ORDER.get(), without every method needing an extra parameter. When the call returns the binding is gone, so nothing can leak into the next task.

Structured concurrency

Lesson 7 showed how to start several lookups and combine them. A remaining problem is cleanup: if one of three lookups fails, the other two should be cancelled, and if the order handler is cancelled, all three should stop. Structured concurrency treats a group of related subtasks as one unit with a clear beginning and end, so that none can outlive the block that started them. Its API, StructuredTaskScope, was a preview feature from Java 21 to Java 27, where its seventh preview (JEP 533) settled the final shape, and JEP 543 makes it a final feature in Java 28, scheduled for March 2027. Code using it on Java 27 needs the --enable-preview option. A sketch of the Java 28 style looks like this:

Java Example · Structured concurrency (final in Java 28)
OrderView view(String orderId) throws Exception {
    try (var scope = StructuredTaskScope.open()) {
        var customer = scope.fork(() -> findCustomer(orderId));
        var prices   = scope.fork(() -> priceLines(orderId));
        scope.join();                     // waits for both; throws if either failed
        return new OrderView(customer.get(), prices.get());
    }                                     // neither subtask can outlive this block
}

What this code does

Two subtasks are forked inside a scope, each on its own virtual thread, and join waits for both. If either fails, the scope cancels the other and join throws, so there is no half-finished work left running. The try-with-resources block guarantees that both subtasks have ended before the method returns.

Structured concurrency and scoped values were designed alongside virtual threads, and together they make the one-thread-per-task style safe as well as cheap. OrderDesk will run on Java 21 with virtual threads and the executor and CompletableFuture tools of lessons 6 and 7; Ingrid notes the structured version as the shape to move to once the shop's computer runs Java 28.

Moving existing code to virtual threads

For most code, switching is a one-line change: replace a fixed thread pool used for waiting tasks with newVirtualThreadPerTaskExecutor. Check a few things when you do. Look for synchronized blocks that wait on slow calls if you are on Java 21. Look for ThreadLocal caches that assumed a small pool. And look for places where the pool size was quietly limiting load on something else, such as a database that allows twenty connections, and replace that hidden limit with an explicit semaphore or a connection pool.

Try it yourself

Ten thousand lookups

Submit 10,000 tasks to a virtual-thread-per-task executor. Task i (from 1 to 10,000) sleeps 10 milliseconds and returns i. Keep the futures in a list and add up their results after the executor has closed.

The program should print tasks: 10000 and sum: 50005000.

import java.util.*;
import java.util.concurrent.*;

public class Main {
    public static void main(String[] args) throws Exception {
        List<Future<Integer>> futures = new ArrayList<>();
        // submit 10,000 tasks to a virtual-thread-per-task executor
        long sum = 0;
        for (Future<Integer> f : futures) sum += f.get();
        System.out.println("tasks: " + futures.size());
        System.out.println("sum: " + sum);
    }
}

Try it yourself

Three at a time

Tamsin's truing stands can hold three wheels. Run 12 wheel jobs on virtual threads, each acquiring one of 3 semaphore permits, sleeping 20 milliseconds and releasing the permit in a finally block. Track the largest number of jobs in progress with atomic variables.

The program should print wheels trued: 12 and never more than 3 at once: true.

import java.util.concurrent.*;
import java.util.concurrent.atomic.AtomicInteger;

public class Main {
    public static void main(String[] args) {
        Semaphore stands = new Semaphore(3);
        AtomicInteger inUse = new AtomicInteger(), most = new AtomicInteger(), done = new AtomicInteger();
        try (ExecutorService ex = Executors.newVirtualThreadPerTaskExecutor()) {
            for (int i = 0; i < 12; i++) {
                ex.submit(() -> {
                    // acquire a stand, record the count, sleep 20 ms, release
                    return null;
                });
            }
        }
        System.out.println("wheels trued: " + done.get());
        System.out.println("never more than 3 at once: " + (most.get() <= 3));
    }
}

Common mistakes

  • MistakePooling virtual threads in a fixed-size pool.

    InsteadCreate one virtual thread per task; limit scarce resources with a Semaphore instead.

  • MistakeUsing virtual threads to speed up CPU-bound calculation.

    InsteadUse a fixed pool of about one thread per core for computing; virtual threads help with waiting.

  • MistakeBlocking on slow calls inside synchronized code on Java 21.

    InsteadUse a ReentrantLock there, or move the slow call outside the critical section.

  • MistakeCaching expensive objects in ThreadLocal with millions of virtual threads.

    InsteadShare a thread-safe instance or use a proper pool; for passing context, consider scoped values on Java 25.

  • MistakeLetting main return before virtual threads finish.

    InsteadVirtual threads are daemons; wait for them with join or a try-with-resources executor.

Summary and key terms

  • Platform threads are operating system threads and are too expensive to create by the tens of thousands.
  • Virtual threads, final in Java 21, are scheduled by the JVM onto a few carrier threads; when one blocks it unmounts, its stack is kept on the heap, and its carrier runs another.
  • They let ordinary blocking code scale to very many concurrent tasks, but they do not speed up calculation.
  • Create them with Thread.ofVirtual(), Thread.startVirtualThread or Executors.newVirtualThreadPerTaskExecutor(); they are always daemon threads.
  • Do not pool them; use a Semaphore to limit access to a scarce resource.
  • On Java 21 blocking inside synchronized pins a virtual thread to its carrier, a limitation removed in Java 24 by JEP 491.
  • ThreadLocal caches lose their point with virtual threads; scoped values, final in Java 25, pass immutable context through a call.
  • Structured concurrency's StructuredTaskScope treats related subtasks as one unit; it was a preview through Java 27 and is final in Java 28.
Virtual thread
A lightweight thread scheduled by the JVM onto carrier threads, cheap enough to create one per task.
Carrier thread
A platform thread on which the JVM runs virtual threads.
Mount and unmount
Attaching a virtual thread to a carrier to run, and detaching it while it waits.
newVirtualThreadPerTaskExecutor
An executor that starts a new virtual thread for every submitted task.
Semaphore
A set of permits that limits how many threads may do something at the same time.
Pinning
A virtual thread holding on to its carrier while it waits, so the carrier cannot run others.
ThreadLocal
A variable with a separate value for each thread.
Scoped value
An immutable value bound for the duration of a call and readable by code called inside it (Java 25).
Structured concurrency
Treating related subtasks as one unit that cannot outlive the block that started it.
StructuredTaskScope
The API for structured concurrency, final in Java 28.

Practice problems

Work each problem on paper first, then reveal the answer to check.

  1. Why can a program have a million virtual threads but not a million platform threads?

    Show answer

    A waiting virtual thread uses only a little heap and no carrier; a platform thread needs an operating system thread and a reserved stack.

  2. Do virtual threads make a CPU-bound sort faster?

    Show answer

    No; there are only as many carriers as cores, and computing keeps them busy.

  3. How should you limit calls to a supplier that allows 5 connections, when using virtual threads?

    Show answer

    With a Semaphore of 5 permits.

  4. What does pinning mean?

    Show answer

    A virtual thread cannot unmount while it waits, so it keeps its carrier busy.

  5. Which Java release removed pinning for synchronized?

    Show answer

    Java 24, through JEP 491.

Lesson quiz · 5 questions

Score 60% or more to complete this lesson.

Take the quiz