What are virtual threads and how do they work in Project Loom?
A virtual thread is an ordinary java.lang.Thread that the JVM schedules itself, without the operating system scheduling it directly. Project Loom keeps the familiar thread API but separates the thread you program against from the OS thread that executes it. Virtual threads run on a small pool of platform threads called carrier threads, typically sized to the number of CPU cores. When a virtual thread starts running, the scheduler mounts it on a carrier.
The cost savings come from what happens when that thread blocks. If a virtual thread waits on a supported operation, such as socket I/O, Thread.sleep, or a java.util.concurrent lock, the JVM unmounts it. Its stack frames move to the heap and the carrier picks up another runnable virtual thread. When the I/O completes, the virtual thread is rescheduled, possibly onto a different carrier. A blocked virtual thread therefore costs some heap memory and does not occupy an OS thread. That is why an application can hold far more of them than it could hold platform threads.
This helps thread-per-request code that spends most of its time waiting on databases, HTTP calls, or message brokers. Blocking servlet stacks can raise concurrency without moving to callback or reactive styles.
Virtual threads do little for CPU-bound work. Computation still needs a core, and you have no more cores than before. WebFlux codebases already avoid blocking threads, so they gain little beyond the option of writing simpler blocking code.
VIRTUAL THREADS (many, cheap, scheduled by the JVM)
+------+ +------+ +------+ +------+ +------+ +------+
| VT 1 | | VT 2 | | VT 3 | | VT 4 | | VT 5 | | ... |
+------+ +------+ +------+ +------+ +------+ +------+
| | | ^
| mount | mount | blocks on | I/O done:
v v | supported op | rescheduled,
+---------------+ | -> unmount | maybe on a
| JVM scheduler | v | new carrier
+---------------+ +-----------------------------------+
| | | UNMOUNTED: VT 4 waiting |
| | | stack frames saved on the heap |
v v | no OS thread or carrier held |
+------+ +------+ | supported ops: socket I/O, |
| CT 1 | | CT 2 | ... | Thread.sleep, j.u.c. locks |
+------+ +------+ +-----------------------------------+
CARRIER THREADS (platform threads, ~ one per CPU core)
| |
v v
+------------------------+
| OS threads / CPU cores |
+------------------------+
CPU-bound VT: never blocks, stays mounted, still needs a core.
Gain = more concurrent waiting, not more compute.
Many virtual threads are mounted by the JVM scheduler onto a small pool of carrier threads, and a virtual thread that blocks on a supported operation unmounts to the heap, freeing its carrier until it is rescheduled.
How do you enable virtual threads in Spring Boot?
Enabling virtual threads is a single property: spring.threads.virtual.enabled=true. The application must also run on a JDK where virtual threads are a final feature, not a preview. With that set, Spring Boot's auto-configuration changes several components that would otherwise draw from platform thread pools.
| Component | Default behaviour | With the property enabled |
|---|---|---|
| Embedded servlet container (Tomcat, Jetty) | Bounded pool of platform worker threads | Each request is handled on a new virtual thread |
Auto-configured applicationTaskExecutor (@Async, async MVC) |
Pooled ThreadPoolTaskExecutor |
SimpleAsyncTaskExecutor that starts a virtual thread per task |
Auto-configured task scheduler (@Scheduled) |
Pooled ThreadPoolTaskScheduler |
SimpleAsyncTaskScheduler that runs each task on a virtual thread |
| Other auto-configured components, such as messaging listener containers | Platform threads from their own executors | Virtual threads, where Spring Boot supplies the executor |
The property covers only beans that Spring Boot configures. If you define your own ExecutorService or TaskExecutor, it keeps its platform threads. Check for those beans, because custom executors are a common reason a migration seems to have no effect.
Virtual threads are daemon threads. An application with no web server, such as one that only runs scheduled jobs, can exit at startup because no non-daemon thread keeps the JVM alive. Setting spring.main.keep-alive=true keeps it running.
To confirm the property took effect, log Thread.currentThread().isVirtual() and the thread's toString() from a request handler and from an @Async method. A virtual thread's string form includes its carrier thread, so you can see which carrier ran the task.
Do not wrap virtual threads in a fixed-size pool. Pools exist because platform threads are expensive to create. Virtual threads are cheap, so you create one per task and let it end when the task finishes. A pool would put back the cap on concurrency that virtual threads remove. To limit concurrency on purpose, use a mechanism built for that, which a later section covers.
// application.properties:
// spring.threads.virtual.enabled=true
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.scheduling.annotation.Async;
import org.springframework.stereotype.Service;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
@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();
// Expect isVirtual=true; toString() shows the carrier, e.g. ...@ForkJoinPool-1-worker-3
log.info("request handler: isVirtual={} thread={}", t.isVirtual(), t);
reportService.generate();
return "virtual=" + t.isVirtual();
}
}
@Service
class ReportService {
private static final Logger log = LoggerFactory.getLogger(ReportService.class);
// Runs on the auto-configured applicationTaskExecutor (needs @EnableAsync on a config class)
@Async
public void generate() {
Thread t = Thread.currentThread();
log.info("@Async method: isVirtual={} thread={}", t.isVirtual(), t);
}
}
With spring.threads.virtual.enabled=true, a request handler and an @Async method each log whether they run on a virtual thread and which carrier thread is executing them.
How does it work inside a Spring Boot request?
The Loom mechanics above become concrete when you follow one request through a blocking Spring MVC service with the property enabled.
- The container accepts the connection. The embedded server still uses its own internal threads to accept connections and detect readable sockets. That part of the container is unchanged.
- The request is dispatched to a new virtual thread. In the default setup, the request would wait for a free thread from the worker pool. With the property enabled, the container hands the request to an executor that starts a fresh virtual thread for it. Filters, the
DispatcherServlet, your controller and your service code all run on that virtual thread, exactly as they did on a platform thread. - Blocking calls park the thread, not the carrier. When the code reaches a blocking JDBC query, an HTTP call made with a blocking client, or a wait on a
java.util.concurrentlock, the virtual thread unmounts. Its carrier immediately runs another request's virtual thread. Your code still reads as a straight line:repository.findById(...)returns a value, and there is no callback orMonoto compose. - The thread resumes when the result arrives. The scheduler mounts the virtual thread on whichever carrier is free. The controller writes the response, and the virtual thread ends. Nothing returns to a pool, because no pool existed.
- Work handed off inside the request follows the same model. An
@Asynccall or a@Scheduledjob runs on the auto-configured executors from the table above, so each task also gets its own virtual thread.
Two things do not change. ThreadLocal values, MDC logging context and Spring's request-scoped and transaction-bound state still work because each request still has its own thread for its whole lifetime. Resource limits also stay where they were: the connection pool still has a fixed number of connections, and the downstream service still has finite capacity. Virtual threads change how many requests can wait at once, not how many can be served at once by those resources. The pinning and backpressure sections below follow from those two facts.
What is thread pinning and why do synchronized blocks matter?
A virtual thread normally unmounts when it blocks: the JVM saves its stack to the heap and frees the carrier platform thread to run other work. Pinning is when that cannot happen. The virtual thread blocks while still attached to its carrier, so the carrier blocks with it.
The classic causes are:
- Blocking inside
synchronizedblocks or methods, such as a JDBC call, socket read, orThread.sleepwhile holding a monitor. - Native or foreign calls, where a JNI or foreign-function frame on the stack prevents the JVM from capturing and moving the thread's state.
Pinning matters because the carrier pool is small, usually sized to the number of CPU cores. Suppose you have eight carriers and eight requests pinned on a slow downstream call. Every other runnable virtual thread then waits, even if there are thousands of them. Throughput falls to the level of a tiny fixed thread pool, and nothing in the logs explains why.
How synchronized interacts with virtual threads has changed across JDK releases. Older blog advice may not apply to the runtime you deploy. Check the release notes for your JDK before treating every monitor as a hazard.
Where synchronized does pin and guards blocking I/O, replace it with ReentrantLock. Acquire the lock, then release it in a finally block so an exception cannot leak the lock. Keep the critical section limited to the shared-state update, and leave unrelated work outside it.
Each migration rewrites code you then have to retest. If your runtime no longer pins on monitors, the rewrite may cost more than it saves.
import java.util.concurrent.locks.ReentrantLock;
public class TokenCache {
// Placeholder for a client that makes a blocking network call.
public interface TokenClient {
String fetchToken(); // blocks on socket I/O
}
private final ReentrantLock lock = new ReentrantLock();
private final TokenClient client;
private String token;
public TokenCache(TokenClient client) {
this.client = client;
}
// Before: on JDKs where monitors pin, a virtual thread blocked in
// fetchToken() here holds its carrier for the whole network call.
//
// public synchronized String get() {
// if (token == null) token = client.fetchToken();
// return token;
// }
// After: a virtual thread blocked while holding a ReentrantLock can
// unmount, so its carrier is free to run other virtual threads.
public String get() {
lock.lock();
try {
// Hold the lock only for the check-and-refresh of shared state.
if (token == null) {
token = client.fetchToken();
}
return token;
} finally {
lock.unlock(); // always released, even if fetchToken() throws
}
}
}
This example replaces a synchronized method that blocks on network I/O with a ReentrantLock released in a finally block, and holds the lock only for the shared-state refresh.
How do you detect pinning in your code and third-party libraries?
You can't fix what you can't see, and pinning is quiet. A pinned virtual thread still finishes its work. The only symptom is that its carrier thread stays blocked, so the scheduler has fewer carriers for everything else.
Tools that expose pinning
JDK Flight Recorder emits a jdk.VirtualThreadPinned event when a virtual thread blocks while pinned beyond a threshold. The event includes a stack trace, which tells you exactly which frame held the carrier. Record under realistic traffic and group the events by top frame.
Thread dumps that include virtual threads, such as those produced by jcmd with Thread.dump_to_file, show what each virtual thread is waiting on. They help when a service has stalled rather than slowed.
Load testing is what makes both tools useful. Pinning only hurts when carriers are scarce, so at low concurrency it rarely appears. This is why it often slips past unit and integration tests. In production it can look like ordinary latency spikes, or like a deadlock when every carrier is pinned waiting on work that needs a free carrier.
Where the risk usually lives
Your own synchronized blocks are the easy part. The larger risk is in dependencies: JDBC drivers, connection pools, HTTP clients, logging appenders and caches. Auditing their source is slow. Profiling under load surfaces the offending frames directly. Also check each library's documentation for stated virtual-thread compatibility.
When you can't fix a dependency
You have three options:
- Upgrade to a release that avoids pinning.
- Replace the library with one that doesn't pin.
- Isolate the call on a dedicated platform-thread executor, so the pinning happens off the carrier pool.
#!/usr/bin/env bash
set -euo pipefail
APP_PID="${APP_PID:?set APP_PID to the JVM process id}"
OUT_DIR=/tmp/pinning-audit
mkdir -p "$OUT_DIR"
jcmd "$APP_PID" JFR.start name=pinning settings=profile \
duration=120s filename="$OUT_DIR/pinning.jfr"
echo "Recording for 120s; drive load against the service now..."
sleep 125
jfr print --events jdk.VirtualThreadPinned "$OUT_DIR/pinning.jfr" \
> "$OUT_DIR/pinned-events.txt"
echo "Pinned events written to $OUT_DIR/pinned-events.txt"
jcmd "$APP_PID" Thread.dump_to_file -format=json \
"$OUT_DIR/threads-$(date +%s).json"
A shell workflow that records jdk.VirtualThreadPinned events with JDK Flight Recorder during a load test, extracts their stack traces, and takes a virtual-thread-aware thread dump for stalled services.
Why do virtual threads need explicit backpressure?
Removing the 200-thread request pool does not remove your limits. It removes the one that used to fail first. A fixed platform-thread pool capped in-flight work implicitly: once every thread was busy, new requests waited in a bounded accept queue or were refused. Virtual threads let every request start, so the excess queues at the next scarce resource, usually the database connection pool.
Illustrative estimate. Assume a 200-thread request pool, 50 ms of downstream latency per request, a 20-connection DB pool, and 1,000 req/s offered load. The DB pool sustains 20 ÷ 0.05 s = 400 req/s in both models. The difference is where the other 600 req/s wait.
| Platform-thread pool (200) | Virtual threads | |
|---|---|---|
| Max throughput | 400 req/s (DB-bound) | 400 req/s (DB-bound) |
| In-flight cap | 200 | None, grows ~600/s |
| Queueing point | Request pool / accept queue | Connection pool wait |
| Overload symptom | Rejections, thread exhaustion | Connection-acquire timeouts, heap growth |
After 10 seconds there are roughly 6,000 parked virtual threads. Each one holds request buffers and partial state, and each will eventually hit a connection timeout.
Bound concurrency at the resource
- Semaphores. Guard each downstream with a semaphore sized to its real capacity. Acquire with a timeout and fail fast when it is not available.
- Pool limits. Treat connection pool size as the deliberate throttle, and keep the acquire timeout short.
- Timeouts. Put timeouts on every outbound call so that waiting work cannot accumulate without bound.
Fix your monitoring
Alerts on "active threads near max" stop firing because the thread count no longer has a ceiling. Replace them with resource-level signals:
- Connection pool wait time and pending acquirers
- Semaphore rejections
- Downstream latency percentiles
- Heap usage after GC
When should you avoid virtual threads, and what are the alternatives?
Virtual threads only help when threads spend most of their time waiting. Several workloads fit that model poorly.
CPU-bound work. Image processing, compression, or heavy serialization keeps a carrier thread busy the whole time. Virtual threads add scheduling overhead and nothing in return, because the bottleneck is cores, not threads. A fixed pool sized near the core count is simpler and more predictable.
Reactive stacks. A WebFlux application already multiplexes I/O on a small event-loop pool. Adding blocking calls on virtual threads gives you two concurrency models, two sets of context-propagation rules, and two ways to debug. Pick one per service.
Heavy ThreadLocal use. Libraries that cache buffers, formatters, or parsers per thread assume a few hundred long-lived threads. With one virtual thread per request, every request allocates a fresh copy. Memory use multiplies and the cache never gets a hit.
Observability cost. A thread dump with hundreds of thousands of entries is hard to read. Per-thread CPU or allocation metrics stop meaning much when each thread lives for one request.
| Approach | Best fit | Development cost | Maintainability risk |
|---|---|---|---|
| Bounded platform-thread pool | CPU-bound or predictable load | Low; familiar model | Pool sizing must track load |
| Reactive (WebFlux) | High-concurrency streaming I/O | High; non-blocking libraries needed end to end | Harder stack traces, steeper onboarding |
CompletableFuture composition |
A few parallel fan-out calls | Moderate | Callback chains and executor choice spread through code |
| Virtual threads | Blocking I/O-heavy services | Low; imperative code stays | Pinning and missing backpressure |
Who should use Spring Boot virtual threads?
The feature fits a specific profile. A team is a good candidate when most of the following are true:
- The service uses the blocking servlet stack. It is built on Spring MVC with JDBC or JPA, blocking HTTP clients, or blocking messaging clients, and the team wants to keep writing imperative code.
- Requests spend most of their time waiting. Profiling shows request threads mostly blocked on databases, other services or brokers, not burning CPU.
- Thread pools are a recurring source of trouble. The team has had incidents caused by worker-pool exhaustion, or spends time tuning
server.tomcat.threads.maxand executor sizes as traffic changes. - Concurrency demand is high or bursty. The service needs many requests in flight at once, for example because it fans out to slow downstream calls, but does not have a matching CPU load.
- The team can upgrade the runtime and dependencies. It can run on a JDK where virtual threads are final, and can upgrade or replace drivers and client libraries if they turn out to pin.
- Someone owns load testing and monitoring. Pinning and missing backpressure only show up under realistic load, so the team needs the means to find them before production does.
Teams in other situations should usually wait or choose differently. Services that are mainly CPU-bound gain nothing. WebFlux services already get high concurrency from their event loops. Services that depend on libraries the team cannot upgrade and that are known to pin carry extra risk. Small internal tools with low, steady traffic rarely hit the limits of a default thread pool, so switching adds little beyond a rollout to manage.
How can virtual threads save engineering time?
The time savings come from work that a blocking Spring Boot service no longer needs, not from faster code.
- Less pool sizing and tuning. With a thread-per-request pool, someone has to pick a worker count, revisit it when latency or traffic changes, and keep it consistent with connection-pool sizes. With virtual threads there is no request worker pool to size. Tuning effort moves to the resources that are really limited, such as connection pools and semaphores, which you needed to understand anyway.
- No reactive rewrite to gain concurrency. The usual way to raise concurrency in a blocking service was to move to a non-blocking stack. That means rewriting service and repository layers, replacing blocking drivers and clients with non-blocking ones, and learning a new operator vocabulary. Virtual threads raise concurrency for the existing code, so that project does not have to happen.
- Simpler debugging. Imperative code on virtual threads produces ordinary stack traces that show the call path from controller to repository. Reactive pipelines and
CompletableFuturechains often produce traces dominated by framework frames, which take longer to read during an incident. - Shorter onboarding and review. Engineers already know sequential, blocking Java. Code review stays focused on business logic rather than on which executor a callback runs on or whether a blocking call slipped into an event loop.
- Fewer pool-exhaustion incidents. Outages caused by every worker thread waiting on one slow dependency become less likely, as long as you put explicit limits and timeouts on that dependency, as described in the backpressure section.
Illustrative estimate. Assume a team owns six blocking services. Assume each service needs one engineer-day per quarter to revisit worker-pool and executor sizing after traffic changes, and that the team is also considering a reactive migration assumed to take four engineer-weeks per service. Enabling virtual threads removes the recurring sizing work, roughly six engineer-days per quarter under these assumptions, and makes the migration unnecessary for services whose goal was only higher concurrency. Against that, budget the one-time work of the rollout below: a pinning audit, lock migrations where needed, and new dashboards. These figures are assumptions for the arithmetic, not measurements. Substitute your own.
The savings only hold if the service fits the profile in the previous section. For CPU-bound or already-reactive services, the migration work is cost with no matching return.
How do you roll out Spring Boot virtual threads safely?
- Enable it in one service, behind configuration. Set
spring.threads.virtual.enabledthrough an environment-specific config source rather than hardcoding it. Pick a blocking, I/O-heavy service with steady traffic so the comparison is meaningful. - Run pinning detection under realistic load. Record a JFR session during a load test and look for
jdk.VirtualThreadPinnedevents. Idle traffic rarely exercises the contended locks inside drivers and client libraries. - Limit concurrency on scarce resources. Put semaphores or bounded pools in front of database connections, rate-limited APIs and memory-heavy work. Without a pool size acting as an accidental throttle, contention moves into those resources.
- Compare against the platform-thread baseline. Check p50, p99 and p99.9 latency, error and timeout rates, and connection-pool wait time. A better median combined with a worse tail usually points to pinning or an unbounded downstream.
- Keep a fast off switch. The property is read at startup, so make sure a config change plus a rolling restart is routine and quick. Practice the rollback before you need it.
This approach removes the per-service work of sizing Tomcat and executor pools, re-tuning them after every traffic shift, and hand-rebalancing them against connection limits. It also avoids rewriting imperative code into reactive pipelines and retraining the team to debug them.
The cost doesn't disappear, though. It moves to other work:
- Auditing
synchronizedblocks in hot paths and dependencies. - Updating dashboards and alerts. Thread-pool saturation metrics stop meaning anything, and thread dumps look different.
- Migrating locks to
ReentrantLockwhere pinning shows up.
Budget for these tasks explicitly.
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.