How do virtual threads work in Java 21?

A virtual thread is a java.lang.Thread that the JVM schedules instead of the operating system. Project Loom made them final in Java 21. The JVM runs virtual threads on a small pool of carrier platform threads, which by default number about the same as the available CPU cores. When a virtual thread blocks on a supported operation, such as socket I/O, Thread.sleep, or most java.util.concurrent locks, the JVM copies its stack frames to the heap and unmounts it. The carrier is then free to run another virtual thread. When the I/O completes, the virtual thread is mounted again, possibly on a different carrier.

The traditional servlet model works differently. Each request takes a platform thread from a fixed pool (a few hundred is typical), and that thread maps one-to-one to an OS thread. A request waiting 80 ms on a database still holds its OS thread for those 80 ms. Throughput under I/O latency is therefore capped at roughly pool size divided by latency, even when the CPU is mostly idle. Making the pool much larger costs memory for each thread stack and adds kernel scheduling overhead.

Platform-thread pool (blocked = held)     Virtual threads on carriers

req1 ──▶ [T1 ████ wait DB ████]           VT1 ─┐ mount     ┌─ unmount on I/O
req2 ──▶ [T2 ████ wait HTTP ██]           VT2 ─┼──▶ [C1] ──┤
req3 ──▶ [T3 ████ wait DB ████]           VT3 ─┤    [C2]   └─▶ heap (parked)
req4 ──▶ (queued: pool exhausted)         ...  ┘   VTn resumes on any free carrier

With virtual threads, blocking no longer occupies an OS thread. Concurrency is limited by heap memory and downstream capacity instead of thread count.

 SERVLET MODEL: fixed pool, 1 platform thread = 1 OS thread
 +--------+     +--------------------------------------+
 | req 1  |---->| T1 [run][ wait on DB ..........][run]|--> OS thread 1
 | req 2  |---->| T2 [run][ wait on HTTP ........][run]|--> OS thread 2
 | req 3  |---->| T3 [run][ wait on DB ..........][run]|--> OS thread 3
 | req 4  |--+  +--------------------------------------+
 +--------+  |   pool exhausted: blocked requests still hold OS threads
             +-> [queue] waits until a pooled thread is released

 VIRTUAL THREADS: many VTs multiplexed on a few carrier platform threads
 +-------+  mount   +----------------------+
 | VT 1  |--------->| carrier C1 runs a VT |--> OS thread 1
 | VT 2  |--------->| carrier C2 runs a VT |--> OS thread 2
 | VT 3  |          +----------------------+    (about one per CPU core)
 |  ...  |                     |
 | VT n  |                     | VT blocks on supported I/O:
 +-------+                     v unmount, stack frames copied to heap
     ^              +----------------------+
     |              | heap: parked VTs     |
     |              | waiting on DB / HTTP |
     |              +----------------------+
     |                         |
     |   I/O completes,        |
     +---- VT runnable --------+
       remounts on any free carrier (C1, C2, ...)

In the servlet model, each blocked request holds a pooled OS thread until the pool is exhausted. Virtual threads unmount to the heap while waiting on I/O, which frees their carrier to run other virtual threads.

How does it work inside a Spring Boot request?

The JVM mechanics above explain how a single virtual thread behaves. In a Spring Boot MVC application with virtual threads enabled, a typical request goes through these steps:

  1. Accept and dispatch. The embedded servlet container accepts the connection. Instead of taking a worker from its bounded thread pool, it hands the request to an executor that starts a new virtual thread for that request.
  2. Run your code unchanged. The DispatcherServlet, filters, interceptors and your @Controller method all run on that virtual thread. The code is the same blocking, imperative code you would write for platform threads.
  3. Block and unmount. When the controller calls a JDBC repository or an outbound HTTP client and waits on the socket, the virtual thread unmounts. Its carrier picks up another runnable virtual thread, which might be a different request.
  4. Resume and respond. When the response bytes arrive, the virtual thread becomes runnable, mounts on any free carrier, finishes the method and writes the HTTP response. The virtual thread then ends. It is not returned to a pool.

Two things do not change. A request still runs on exactly one thread from start to finish, unless your code hands work to another executor, so request-scoped state behaves as before. Each request also still needs whatever downstream resources it uses, such as a database connection. Virtual threads remove the cost of waiting. They do not remove the cost of the resource you wait for. The later sections on pinning and connection pools follow from these two points.

Why use Spring Boot virtual threads instead of going reactive?

That lifts the ceiling that pushed many teams toward reactive stacks in the first place. A blocked request now costs a small heap-allocated stack instead of an OS thread, so the case for rewriting imperative code to avoid blocking gets much weaker.

Approach Programming model Debuggability Backpressure Streaming Migration effort
Tuned platform-thread pool Blocking, imperative Full, readable stack traces Implicit via pool size and queue Servlet streaming, SSE None, but the thread ceiling stays
WebFlux / reactive Operator chains, non-blocking Fragmented traces across operators Built in (Reactive Streams) First-class High: rewrite plus non-blocking drivers
CompletableFuture composition Callbacks and futures Traces split at async boundaries Manual Awkward Medium, and it spreads through signatures
Virtual threads Blocking, imperative Full stack traces Manual: semaphores, pool limits Servlet streaming, SSE Low: configuration and an audit

Engineering cost drives most adoption decisions. Your existing JDBC repositories, RestClient calls and @Transactional methods keep working without changes. A debugger breakpoint or a thread dump shows the actual call path, and new hires can read the code without first learning reactive operators.

Reactive still makes sense when you need end-to-end backpressure, long-lived streaming connections or a fully non-blocking stack that is already in place. Virtual threads do not remove the remaining work. You still need to profile for pinning, put explicit limits around downstream resources and load-test under real concurrency. That work is smaller than a rewrite, and the following sections cover it.

How can virtual threads save engineering time?

The savings come from work you no longer need to do, not from faster code.

  • No rewrite to scale I/O-bound endpoints. Moving to a reactive stack means changing controller signatures, replacing JDBC with a non-blocking driver, rewriting transaction handling and retraining the team. With virtual threads, the migration is a property, a review of your own executors and a pinning audit. The domain code stays as it is.
  • Less thread-pool tuning. You no longer have to balance request-pool size against memory and context-switching cost, or keep re-tuning it as downstream latency shifts. The tuning that remains is about the downstream resources themselves, such as connection pool sizes, semaphore permits and timeouts, which you had to reason about anyway.
  • Faster debugging and incident response. Stack traces show the real call chain from controller to driver. A breakpoint pauses at a line that makes sense in context. On-call engineers do not have to reconstruct a request's path across operator chains or callback boundaries.
  • Existing tests and tooling keep working. Unit and integration tests written for blocking code still apply, and so does test support built around the servlet stack, such as MockMvc-style tests and transactional test rollbacks.
  • Simpler code reviews and onboarding. Sequential code reads top to bottom. Reviewers do not need to check for accidental blocking calls inside reactive pipelines, which is a common and hard-to-spot class of bug in mixed codebases.
  • Fewer special-purpose async paths. Code that was split into CompletableFuture chains only to avoid holding a pooled thread can often go back to plain sequential calls, or to a simple per-task virtual-thread executor for fan-out.

The time is not entirely free. Budget for the audit described below: finding pinning in your code and dependencies, adding bulkheads and timeouts around each downstream dependency, reviewing ThreadLocal usage and running a realistic load test. Those tasks are bounded and can be done incrementally, while a reactive rewrite touches every layer of the service.

Who should use Spring Boot virtual threads?

Virtual threads fit best for:

  • Teams running Spring MVC on the servlet stack whose services spend most of their request time waiting on databases, HTTP calls, caches or message brokers.
  • Services where the request thread pool is the observed limit, meaning threads are saturated while CPU stays low and downstream dependencies still have spare capacity.
  • Teams that considered a reactive rewrite only for scalability, not because they needed streaming or end-to-end backpressure.
  • Services with fan-out calls to several dependencies per request, where a per-task virtual-thread executor replaces a tuned thread pool.
  • Organisations that can run Java 21 or later in production and keep their JDK reasonably current, since pinning behaviour and diagnostics change between releases.

They are a weaker fit for:

  • CPU-bound services, where threads are busy computing rather than waiting, so there is nothing to unmount.
  • Applications already built on WebFlux that rely on streaming and backpressure.
  • Services whose real limit is a small database pool or slow queries. Virtual threads let more requests reach that limit at once, but they do not raise it.
  • Codebases that depend heavily on libraries that pin carriers, until those libraries are upgraded or replaced.
  • Teams that cannot move off Java versions earlier than 21.

The final section turns these criteria into a decision table.

How do you enable virtual threads in Spring Boot?

The starting point is one property: set spring.threads.virtual.enabled=true in application.properties and run on Java 21 or later. Spring Boot then configures the embedded servlet container to handle each request on a virtual thread, and switches its auto-configured task executors to virtual threads as well. Exactly which components are covered has changed between releases, so check the reference documentation for your Spring Boot version and do not assume full coverage.

The property only reaches beans that Spring Boot creates for you. You need to change these yourself:

  • Custom ExecutorService beans. A ThreadPoolExecutor you declared still uses platform threads.
  • Hand-defined @Async executors. If @Async("reportExecutor") points to your own bean, the property has no effect on it.
  • Scheduled tasks that run on a scheduler you defined.
  • Third-party libraries that create their own pools, such as messaging consumers, HTTP clients and SDKs.

To migrate your own code, replace fixed pools with Executors.newVirtualThreadPerTaskExecutor(), which starts a new virtual thread for each submitted task. For a single thread, use Thread.ofVirtual().name("worker-", 0).start(task).

Do not pool virtual threads. A pool is useful when threads are expensive to create and you want to reuse them. Virtual threads are cheap enough to create one per task. A pool of 200 virtual threads brings back the 200-task ceiling you were trying to remove. If you need a pool because you want to limit concurrency against a database or an API, use a Semaphore or a bounded connection pool around that specific resource.

// application.properties: spring.threads.virtual.enabled=true (Java 21+)
// That covers Spring Boot's own executors. The beans below are yours, so you migrate them.
import java.util.concurrent.*;
import org.springframework.context.annotation.*;
import org.springframework.scheduling.annotation.*;
import org.springframework.stereotype.Service;

@Configuration
@EnableAsync
class VirtualThreadConfig {
    // Was a fixed ThreadPoolExecutor. Now each task gets a new virtual thread, with no pool.
    @Bean("reportExecutor")
    ExecutorService reportExecutor() {
        return Executors.newVirtualThreadPerTaskExecutor();
    }
}

@Service
class ReportService {
    // Cap concurrency at the downstream API, not by limiting the number of threads.
    private final Semaphore apiPermits = new Semaphore(20);
    // Reuse one builder so the name counter increments: worker-0, worker-1, ...
    private final Thread.Builder workers = Thread.ofVirtual().name("worker-", 0);

    @Async("reportExecutor")
    public void generate(String reportId) throws InterruptedException {
        apiPermits.acquire();
        try {
            callReportingApi(reportId);
        } finally {
            apiPermits.release();
        }
    }

    Thread startWorker(Runnable task) {
        return workers.start(task);
    }

    private void callReportingApi(String reportId) { /* blocking HTTP call */ }
}

A hand-defined @Async executor switched to Executors.newVirtualThreadPerTaskExecutor(), a Semaphore that limits concurrency against a downstream API instead of a thread pool, and Thread.ofVirtual() for starting individual named virtual threads.

What is thread pinning and how do you detect it?

Even without a fixed pool, a virtual thread can lose its main advantage. On Java 21, a virtual thread that blocks inside a synchronized block or method, or during a native call, cannot unmount. It stays pinned to its carrier platform thread. The carrier pool defaults to roughly one thread per CPU core, so a handful of pinned requests waiting on a slow socket can occupy every carrier. Throughput then drops back to the old ceiling, now set by core count instead of pool size. Nothing errors. Latency rises and the cause looks like a slow database.

Your own code is the easy part. Pinning often comes from places you don't control: JDBC drivers that guard socket reads with synchronized, connection pools, HTTP clients, and logging appenders.

Detecting it

  • JFR: record with Java Flight Recorder and look for jdk.VirtualThreadPinned events. Each event includes a stack trace and duration, so you can see which frames held the carrier and for how long.
  • System property: start the JVM with -Djdk.tracePinnedThreads=full (or short) to print a stack trace when a virtual thread blocks while pinned. It is useful in load tests, but too noisy for production.

Fixing it

When a synchronized section held for a long time performs I/O, replace it with java.util.concurrent.locks.ReentrantLock. Virtual threads waiting on a ReentrantLock unmount and free the carrier. Keep synchronized for short critical sections that only touch memory. For third-party code, upgrade to versions that have already made this change.

Later JDK releases change the pinning rules and the diagnostics, including how synchronized behaves and which flags exist. Re-check this guidance whenever you upgrade.

import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.concurrent.locks.ReentrantLock;

// Run a load test with -Djdk.tracePinnedThreads=full, or record with JFR
// and inspect jdk.VirtualThreadPinned events, to find sections like this.
public class TokenCache {

    private final HttpClient http = HttpClient.newHttpClient();
    private final ReentrantLock lock = new ReentrantLock();
    private String token;

    // Before (pins on Java 21): the virtual thread holds a monitor while
    // blocked on network I/O, so it cannot unmount from its carrier.
    //   public synchronized String get() { ... http.send(...) ... }

    // After: a virtual thread blocked here, or waiting for the lock,
    // unmounts and frees the carrier for other virtual threads.
    public String get() throws IOException, InterruptedException {
        lock.lock();
        try {
            if (token == null) {
                HttpRequest req = HttpRequest.newBuilder(
                        URI.create("")).build();
                token = http.send(req, HttpResponse.BodyHandlers.ofString()).body();
            }
            return token;
        } finally {
            lock.unlock(); // always release, even if the request throws
        }
    }
}

Replacing a synchronized method that performs a blocking HTTP call with a ReentrantLock so virtual threads on Java 21 can unmount instead of pinning their carrier.

Why does the bottleneck move to connection pools and downstream services?

With a bounded platform-thread pool, Tomcat's worker count quietly acted as a concurrency limit. If the pool had a few hundred threads, at most a few hundred requests could be inside your code at once, and everything downstream was sized against that ceiling whether anyone planned it or not. Virtual threads remove that ceiling. A traffic spike now becomes thousands of concurrent requests that all reach the JDBC pool, the HTTP client's connection pool, and any rate-limited third-party API at the same time.

The connection pool becomes the real limit

If the JDBC pool holds 20 connections, the effective database concurrency is 20. The other requests park while waiting for a connection. Parking is cheap, so memory holds up, but latency grows with the length of the queue. Do not respond by raising the pool size to match request volume. The database pays for every connection in memory, lock contention and context switching, and a database that the thread cap used to protect can now be overloaded directly.

Make backpressure explicit

  • Size pools for the dependency, not the caller. Base the size on what the database or service can sustain.
  • Set a short connection-acquisition timeout. A request should fail fast rather than wait indefinitely for a connection.
  • Add a Semaphore bulkhead around each dependency. Use tryAcquire with a timeout, so excess load is rejected with a clear error instead of piling up.
  • Set timeouts on every outbound call. Without them, a slow dependency holds permits and connections until callers give up.
import java.io.IOException;
import java.net.URI;
import java.net.http.*;
import java.time.Duration;
import java.util.concurrent.*;

// Bulkhead for one downstream dependency. Size it for what the service
// can sustain, not for how many virtual threads may call it.
public class InventoryClient {
    private static final int MAX_CONCURRENT_CALLS = 20;
    private final Semaphore permits = new Semaphore(MAX_CONCURRENT_CALLS);

    // Connect timeout bounds TCP setup. Per-request timeout bounds the whole call.
    private final HttpClient http = HttpClient.newBuilder()
            .connectTimeout(Duration.ofSeconds(2))
            .build();

    public String fetchStock(String sku) throws IOException, InterruptedException {
        // Wait briefly for a permit, then reject instead of queueing without limit.
        if (!permits.tryAcquire(200, TimeUnit.MILLISECONDS)) {
            throw new BulkheadFullException("inventory service saturated");
        }
        try {
            HttpRequest request = HttpRequest.newBuilder(
                            URI.create("" + sku))
                    .timeout(Duration.ofSeconds(3)) // a slow dependency cannot hold a permit forever
                    .GET()
                    .build();
            return http.send(request, HttpResponse.BodyHandlers.ofString()).body();
        } finally {
            permits.release(); // always return the permit, including on timeout or error
        }
    }

    // Map this to HTTP 503 or 429 so callers can back off and retry.
    public static class BulkheadFullException extends RuntimeException {
        public BulkheadFullException(String message) { super(message); }
    }
}

A Semaphore bulkhead with a bounded tryAcquire wait and explicit connect and request timeouts limits concurrent calls to one downstream service, however many virtual threads call it.

How do ThreadLocal, MDC and observability behave with virtual threads?

Thread-locals still work with virtual threads, but their cost model changes. With around 200 pooled platform threads, a ThreadLocal holding a buffer, a parser, or a cached connection was effectively a small per-worker pool: 200 copies, reused across millions of requests. With one virtual thread per request, nothing is reused. Every request allocates its own copy, populates it once and discards it. A 64 KB per-thread buffer goes from a fixed cost to garbage multiplied by concurrency. Audit ThreadLocal caches and connection-per-thread patterns, and replace them with explicit, bounded pools. Large MDC maps have the same issue, so keep MDC entries to a few short identifiers.

MDC and Spring Security's SecurityContextHolder behave correctly within a single request, because the request stays on one virtual thread. Context is lost when work moves to another thread, such as an executor, an @Async method or a parallel fan-out. Propagate it explicitly with a TaskDecorator or a context-propagating executor wrapper, and confirm that trace and span IDs survive those hops. Scoped values are the longer-term replacement for this pattern: immutable, bounded context inherited by child tasks. Treat them as a future direction, not something to build on today.

Tooling also needs adjusting:

  • Thread dumps from classic tools may omit virtual threads. Use the jcmd thread-dump-to-file command.
  • "Active threads" metrics no longer indicate saturation. Track in-flight requests, pool wait time and permit usage instead.
  • APM agents and libraries that assume pooled threads may misattribute work or pin carrier threads. Verify them under load before rollout.

How do you measure whether virtual threads helped, and when should you avoid them?

Verify them under load before trusting their numbers.

Measuring the change

Run the same load test against both configurations, using stubbed downstreams with realistic injected latency. Against a fast local mock, blocking costs almost nothing and both models look the same. Compare four things: throughput at a fixed error budget, p99 latency, heap usage (each parked virtual thread keeps its stack on the heap), and connection-pool wait time. If p99 improves but pool wait rises, the bottleneck has moved, not gone away. To see what virtual threads are doing, take a thread dump with jcmd <pid> Thread.dump_to_file, which includes virtual threads, and record JFR with pinning events enabled.

Illustrative estimate. These inputs are assumed, not measured. Little's Law gives concurrency = throughput × latency.

  • Platform threads: 200 threads ÷ 0.1 s = about 2,000 req/s ceiling.
  • Virtual threads: the thread cap goes away. If each request holds a database connection for the whole 100 ms, then 50 connections ÷ 0.1 s = about 500 req/s in both models. If each request holds a connection for only 10 ms, the database ceiling rises to about 5,000 req/s, and virtual threads can exceed the platform-thread cap.

When to adopt or avoid

Situation Virtual threads?
Blocking I/O-heavy service, thread pool saturated Yes
CPU-bound work No: no gain, plus scheduling overhead
WebFlux stack relying on streaming and backpressure No: keep it
Small database pool already the limit Not until you fix the pool or the queries
Heavy synchronized around blocking calls Only after you remove the pinning

How OneEnv can help

Disclosure: OneEnv is the product behind this blog.

OneEnv (oneenv.io) is a workspace-based governance platform for the things services share — environment variables, database structure, API routes and validation rules. A change to a shared value is staged on a branch, reviewed once, and then every affected service explicitly approves or rejects it before it goes live, so you can see who a change touches before it ships instead of finding out in production.

Applied to spring boot virtual threads, this is where it helps:

Saves time

  • Every service that inherits a shared value is listed in one place, so nobody searches repos and chats to find out who is affected.
  • One review per branch replaces coordinating each team separately; each service still keeps its own approve/reject.
  • Reviewers see the exact diff and the list of affected services up front, so approval is a decision rather than an investigation.

Saves cost

  • Fewer production incidents and rollbacks caused by a shared value, route or column changing under a consumer unannounced.
  • Less duplicated configuration to maintain: one shared definition inherited by many services.
  • Per-service approve/reject means a bad shared value can be refused where it would break something, before it is live.
  • OneEnv has a free plan (1 workspace, unlimited services and members, full governance), so trying it costs nothing.

These are qualitative benefits, not measured results — how much you save depends on how many services share the value.

Want to try it? Start at oneenv.io.