How do virtual threads work under Project Loom?
A virtual thread is a java.lang.Thread that the JVM schedules instead of the operating system. Virtual threads became a final feature in Java 21 under Project Loom, and this article uses Java 21 as its baseline. Many virtual threads share a small pool of platform threads called carriers. By default the carrier pool is a ForkJoinPool sized to the number of available cores.
When a virtual thread reaches a blocking operation that the JDK can park, such as a socket read, Thread.sleep, or waiting on a java.util.concurrent lock, the JVM unmounts it. Its stack frames are saved to the heap, and the carrier is free to run another virtual thread. When the operation completes, the scheduler mounts the virtual thread again, possibly on a different carrier, and execution continues from where it stopped.
This is why you can write plain blocking code and still get much of the scalability of async code. Async frameworks avoid tying up threads by splitting work into callbacks. Loom avoids the same cost by making each blocked thread cheap: a few kilobytes of heap rather than an OS thread with its own reserved stack. Your stack traces, try/catch blocks and sequential control flow stay as they are.
The mechanism fails when a virtual thread cannot unmount. In Java 21 this happens if it blocks inside a synchronized block or during a native call. In that case it is pinned, and it holds its carrier for the entire wait.
| Carrier | Currently mounted | Waiting to mount |
|---|---|---|
| Carrier 1 | VT-1 (running) | VT-4, VT-7 |
| Carrier 2 | VT-2 (pinned: blocked on I/O inside synchronized) |
VT-5, VT-8 |
| Carrier 3 | VT-3 (running) | VT-6, VT-9 |
| (parked on heap, using no carrier) | VT-10 (waiting on socket read) | — |
Runnable virtual threads (waiting for a carrier)
+------------+ +------------+ +------------+
| VT-4 VT-7 | | VT-5 VT-8 | | VT-6 VT-9 |
+-----+------+ +-----+------+ +-----+------+
| mount | mount | mount
v v v
+-------------------------------------------------------+
| Carrier pool: ForkJoinPool, parallelism = CPU cores |
| |
| +-------------+ +---------------+ +-------------+ |
| | Carrier 1 | | Carrier 2 | | Carrier 3 | |
| | VT-1 | | VT-2 PINNED | | VT-3 | |
| | running | | I/O inside | | running | |
| | | | synchronized: | | | |
| | | | carrier held | | | |
| +------+------+ +---------------+ +-------------+ |
+---------|---------------------------------------------+
| unmount on parkable block (socket read)
v
+-----------------------------------+
| Heap: parked VT-10 |
| stack frames saved, no carrier |
+-----------------+-----------------+
| I/O completes: back to runnable queue
+--> remount on any free carrier
Many virtual threads multiplexed over a few carrier threads in Java 21: VT-10 unmounts to the heap while it waits on a socket read and frees its carrier, while VT-2 is pinned inside a synchronized block and holds Carrier 2 for the whole wait.
When do Spring Boot virtual threads actually improve throughput?
Teams adopt virtual threads to raise the concurrency ceiling of a request-per-thread server without rewriting code in a reactive style. Little's law explains the ceiling: in-flight requests = throughput × latency, so throughput ≤ concurrency ÷ latency. When each in-flight request holds a platform thread, the pool size sets the concurrency.
Illustrative estimate (assumed inputs, not measured)
Assume a fixed pool of 200 platform threads and a 100 ms per-request wait on a downstream call. The ceiling is 200 ÷ 0.1 s ≈ 2,000 requests/s. Above that rate, requests queue for a thread while the CPU sits mostly idle.
With virtual threads, a waiting request parks on the heap instead of holding an OS thread, so the thread cap disappears. The next limit takes over. Assume each request also uses 2 ms of CPU on 8 cores. The new ceiling is 8 ÷ 0.002 s ≈ 4,000 requests/s, or lower if a connection pool or downstream rate limit is tighter.
| Workload | Limited by thread-pool size? | Effect of virtual threads |
|---|---|---|
| Blocking I/O: JDBC, HTTP clients, queues | Yes | Higher ceiling until the next resource saturates |
| CPU-bound: encoding, crypto, computation | No | No faster; tail latency may get worse |
| Already non-blocking (reactive) | No | Little to gain |
The strongest candidates are blocking, I/O-bound services whose throughput plateaus while threads sit waiting. CPU-bound work gets no faster because the core count is unchanged. Admitting more concurrent requests to compete for those cores adds scheduling contention, which can worsen tail latency.
How do you enable and verify virtual threads in Spring Boot?
Turning virtual threads on requires a single property, spring.threads.virtual.enabled=true, and a JDK that supports them (Java 21 or later). With it set, Spring Boot configures the embedded web server to handle each request on a virtual thread. It also switches its auto-configured task executor and scheduler, which back @Async methods and @Scheduled jobs, to virtual threads. Exactly which components follow the property has changed between releases, so check the documentation for your Spring Boot version. Do not assume every executor in your application moved over. Thread pools you construct yourself are not affected and keep using platform threads.
Verify the switch at runtime
Check what is actually running instead of trusting the configuration. In one request handler and one @Async method, log Thread.currentThread().isVirtual() and the thread's name. A misconfigured profile, an older Spring Boot version, or a custom executor bean that replaces the auto-configured one can each leave you on platform threads without any error. Virtual threads are often unnamed, so logging the full Thread.currentThread() string is more informative because it marks the thread as virtual. Run this check in each environment, not only on a developer laptop.
Why the migration is cheap
Your blocking code stays as written. JDBC calls, synchronous HTTP clients, and imperative control flow keep working, and stack traces still read top to bottom through your own methods. You do not rewrite services into a reactive style.
What still costs effort
You still need to audit dependencies for pinning, which the next section covers. You also need to adjust observability. Thread-pool saturation metrics stop meaning much, and thread dumps can contain far more threads than before.
// application.properties: spring.threads.virtual.enabled=true (requires Java 21+)
@SpringBootApplication
@EnableAsync // @Async methods run on Spring's auto-configured task executor
public class DemoApplication {
public static void main(String[] args) { SpringApplication.run(DemoApplication.class, args); }
}
@RestController
class ThreadCheckController {
private static final Logger log = LoggerFactory.getLogger(ThreadCheckController.class);
private final ReportService reportService;
ThreadCheckController(ReportService reportService) { this.reportService = reportService; }
@GetMapping("/thread-check")
String check() {
Thread t = Thread.currentThread();
// Virtual threads are often unnamed; toString() still marks them as virtual
log.info("request virtual={} name='{}' thread={}", t.isVirtual(), t.getName(), t);
reportService.generate(); // check the async path as well
return "virtual=" + t.isVirtual();
}
}
@Service
class ReportService {
private static final Logger log = LoggerFactory.getLogger(ReportService.class);
@Async
public void generate() {
Thread t = Thread.currentThread();
// false here can mean a custom executor bean replaced the auto-configured one
log.info("@Async virtual={} name='{}' thread={}", t.isVirtual(), t.getName(), t);
}
}
With spring.threads.virtual.enabled=true set, this app logs isVirtual(), the thread name, and the thread string from a request handler and an @Async method, so you can confirm the switch in each environment instead of assuming it.
What is thread pinning and how do you detect it?
A virtual thread is pinned when it blocks but cannot unmount from its carrier. The scheduler normally frees the carrier by copying the virtual thread's stack to the heap. That fails when the stack holds a frame the JVM cannot safely move. The blocked virtual thread then keeps the platform thread for the whole wait.
There are two classic causes. The first is blocking inside a synchronized block or method on older JDKs, because monitor ownership was tied to the carrier thread. The second is blocking while a native or foreign-function frame is on the stack. Newer JDKs have largely removed the synchronized case, but native-frame pinning remains. Check your JDK's release notes, and treat Java 21 behavior as the conservative baseline when you reason about libraries you don't control.
Pinning matters because the carrier pool is small, usually sized to the number of cores. A few pinned threads waiting on slow I/O can occupy every carrier. Thousands of runnable virtual threads then queue behind them, and throughput collapses even though CPU sits idle. If a pinned thread is waiting on something only an unscheduled virtual thread can provide, such as a lock release or a pooled connection, the scheduler can deadlock.
Detecting it
JDK Flight Recorder emits a jdk.VirtualThreadPinned event with the stack trace of the blocking call. That event is the most reliable signal in production-like runs. Thread dumps that include virtual threads, such as those from jcmd's thread-dump-to-file command, show what each one is parked on. The older jdk.tracePinnedThreads system property depends on the JDK version, so don't build tooling around it.
Expect pinning to stay invisible at low load. It only shows up when concurrency exceeds the carrier count, so run load tests at realistic concurrency.
#!/usr/bin/env bash
# Capture pinning evidence from a running Spring Boot app during a load test.
# Run this while the load generator drives concurrency well above the core count.
set -euo pipefail
PID=$(pgrep -f 'orders-service.jar' | head -n 1) # placeholder app name
OUT=/tmp/pinning-$(date +%s)
mkdir -p "$OUT"
# 1. Start a time-boxed JFR recording. The 'profile' settings enable
# jdk.VirtualThreadPinned, which records the stack of each blocking call
# that held its carrier longer than the event threshold.
jcmd "$PID" JFR.start name=pinning settings=profile duration=120s \
filename="$OUT/pinning.jfr"
# 2. Midway through the run, take a thread dump that includes virtual threads.
# The JSON format lists each virtual thread and what it is parked on.
sleep 60
jcmd "$PID" Thread.dump_to_file -format=json "$OUT/threads.json"
# 3. Wait for the recording to finish and be written to disk.
sleep 65
# 4. Extract only the pinned events. Look at the top frames of each stack:
# a synchronized method or a native frame directly under the blocking call
# points at the cause.
jfr print --events jdk.VirtualThreadPinned "$OUT/pinning.jfr" \
> "$OUT/pinned-events.txt"
echo "Pinned events: $(grep -c 'jdk.VirtualThreadPinned' "$OUT/pinned-events.txt" || true)"
echo "Artifacts in $OUT"
A shell script that records jdk.VirtualThreadPinned events with JFR and takes a virtual-thread-aware thread dump from a running app under load, then filters the recording down to pinned events and their stack traces.
How do you fix pinning in your code and dependencies?
On a JDK that still pins, the fix in your own code is to replace synchronized blocks that wrap blocking I/O with a java.util.concurrent.locks.ReentrantLock. A virtual thread that blocks on I/O inside a monitor stays mounted on its carrier, because the JVM tracks monitor ownership against the carrier thread. A ReentrantLock is built on LockSupport.park, which the virtual-thread scheduler understands, so the thread can unmount while it waits and free the carrier for other work. The before/after example below makes this swap. The semantics stay the same, but you must release the lock in a finally block yourself, since a ReentrantLock is not released automatically the way a monitor is when its block exits. You don't need to replace synchronized blocks that guard only short in-memory work. They hold the carrier for microseconds, and changing them adds risk with no benefit.
Dependencies need an audit. Run a load test with pinning detection enabled and group the reported stack frames by package. The usual suspects are:
- JDBC drivers
- connection pools
- HTTP clients
- caching libraries whose loaders do I/O
All four have historically guarded sockets, pool state, or cache computation with synchronized. Where you have a choice, prefer library versions whose maintainers explicitly state virtual-thread compatibility in their release notes. If a library can't be fixed, route those calls through a small, bounded platform-thread executor.
Pinning in third-party code is outside your control. A dependency upgrade can remove it, and an upgrade can also introduce it. Treat pinning checks as part of your regression load tests, not as a one-off migration task.
import java.io.IOException;
import java.util.concurrent.locks.ReentrantLock;
// BEFORE: blocking I/O inside a monitor pins the virtual thread to its carrier
class ReportClientBefore {
private final Object lock = new Object();
String fetch(String id) throws IOException {
synchronized (lock) {
return remoteCall(id); // carrier stays occupied for the whole call
}
}
private String remoteCall(String id) throws IOException { return "report-" + id; }
}
// AFTER: same mutual exclusion, but waiting parks instead of pinning
class ReportClientAfter {
private final ReentrantLock lock = new ReentrantLock();
String fetch(String id) throws IOException {
lock.lock();
try {
return remoteCall(id); // virtual thread can unmount while blocked
} finally {
lock.unlock(); // must release explicitly, unlike a monitor
}
}
private String remoteCall(String id) throws IOException { return "report-" + id; }
}
Replacing a synchronized block around a blocking remote call with a ReentrantLock released in finally, so a virtual thread can unmount from its carrier while waiting on JDKs that still pin.
Where does the bottleneck move after threads become cheap?
Before virtual threads, a Tomcat pool of a few hundred threads acted as backpressure that nobody designed. Excess requests waited in the accept queue, and downstream systems were shielded from load. With one virtual thread per request, that limit disappears. Concurrency is now capped by the first finite resource each request touches: the JDBC connection pool, the HTTP client's per-host connection limit, or a partner API's rate limit. Requests still queue. They wait on that pool, often with a less visible timeout.
Size pools deliberately and watch wait time
Size the connection pool for what the database can sustain, not for the number of incoming requests. Then alert on connection acquire time and pending-request counts. Rising acquire time means the pool, not the CPU, is your limit.
For downstream calls without a natural pool, wrap the call in a Semaphore sized to the agreed concurrency, and use a bounded tryAcquire timeout. This makes the limit explicit, testable, and independent of how threads are scheduled.
Anti-patterns to remove
- Pooling virtual threads. Create one per task. A pool only reintroduces the cap.
- ThreadLocal caches of expensive objects. Formatters or buffers that were reused across a few hundred pooled threads are now built once per request, which multiplies memory and allocation.
- Fixed-size executors kept out of habit. They quietly cancel the benefit.
Observability changes
- Thread-count metrics: JVM thread-count metrics typically report platform threads only.
- MDC logging: MDC still works per thread, but you must propagate it explicitly when handing work to new threads.
- Profilers: Some profilers attribute samples to carrier threads.
- Thread dumps: Dumps can contain hundreds of thousands of entries. Use
jcmd <pid> Thread.dump_to_filewith JSON output and filter it with tools rather than reading it by hand.
Virtual threads vs WebFlux: when should you avoid migrating?
There are three viable options, not two: virtual threads, reactive WebFlux, and a well-tuned platform-thread pool. Each one carries different risks.
| Concern | Virtual threads | WebFlux (reactive) | Tuned platform pools |
|---|---|---|---|
| Programming model | Imperative, blocking style | Declarative operator chains | Imperative, blocking style |
| Stack traces and debugging | Normal, readable traces; standard debuggers work | Fragmented traces across operators; needs extra tooling | Normal, readable traces |
| Backpressure semantics | None built in; you add limits | Explicit, part of the stream contract | Implicit via pool and queue size |
| Ecosystem maturity | Depends on drivers being free of pinning | Requires non-blocking drivers end to end | Mature everywhere |
| Sensitivity to pinning | High | Not applicable | Not applicable |
| Development cost | Low for existing MVC code | High: rewrite and retraining | Lowest: configuration only |
Virtual threads keep your imperative code and your existing profilers, debuggers and logging context. Reactive gives you something they do not: backpressure built into the stream contract, plus operators for streaming, windowing and merging. With virtual threads you have to rebuild that control yourself.
When to avoid migrating
- CPU-bound services. The work is limited by cores, not by threads waiting on I/O, so cheaper blocking does not help.
- Reactive services that depend on streaming or high fan-out. Moving to virtual threads means giving up working backpressure and operator composition, and you gain little in return.
- Native-heavy stacks. Libraries that call into native code can pin carrier threads, and you may not be able to fix them.
Decision checklist
- JDK 21 or later, and you have confirmed which pinning behaviours your release still has.
- Every driver and client library has been audited for pinning.
- Concurrency limits are set explicitly for each downstream system, using semaphores or bulkheads.
- Load tests show a throughput or latency gain over a tuned pool, using production-shaped traffic.
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.
- Changing a shared variable is one edit and one review instead of editing every service's
.envby hand.
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.
- A wrong or stale value is caught at review time by the services it affects, not by a failed deploy.
- 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.