What are virtual threads and what do they change for a Spring Boot service?
Virtual threads, delivered by Project Loom, are threads managed by the JVM rather than the operating system. Each one is a cheap heap object, so a service can create one per request without a pool. They run on a small set of platform threads called carriers, usually about one per CPU core.
The key change happens at blocking calls. When a virtual thread waits on a socket read, a JDBC query, or an outbound HTTP response, the JVM parks it and saves its stack to the heap. The carrier is then free to run another virtual thread. When the I/O completes, the parked thread is scheduled back onto any available carrier. You keep the thread-per-request model and readable blocking code, but a fixed platform thread pool no longer limits concurrency.
What it changes on the request path
- Tomcat accepts the connection and hands the request to a new virtual thread instead of a pooled worker.
- Carrier threads run your controller and service code, and are released whenever that code blocks.
- The JDBC connection pool and HTTP client connection pool now cap concurrency. Thousands of requests can be in flight, but only as many can query the database as there are pooled connections.
Throughput improves only when requests spend most of their time waiting on I/O. CPU-bound handlers gain nothing, because the cores are already busy.
This model fits teams running blocking, I/O-bound REST services on the servlet stack. These teams want higher concurrency without rewriting their code in a reactive style.
Clients: many concurrent HTTP requests
|
v
+------------------------------------------------------------+
| Tomcat connector: accepts the connection |
| and starts one new virtual thread per request (no pool) |
+------------------------------------------------------------+
|
v
+------------------------------------------------------------+
| Virtual threads: cheap heap objects, thousands in flight |
| [VT1] [VT2] [VT3] [VT4] ... [VTn] |
| running: mounted on a carrier, executes controller code |
| parked: blocked on I/O, stack saved to heap, carrier free |
+------------------------------------------------------------+
| mount on a carrier / unmount at each blocking call
v
+------------------------------------------------------------+
| Carrier platform threads (about one per CPU core) |
| [C1] [C2] [C3] [C4] |
+------------------------------------------------------------+
| |
v JDBC query v outbound HTTP call
+-------------------------+ +----------------------------+
| JDBC connection pool | | HTTP client conn. pool |
| N connections = LIMIT | | M connections = LIMIT |
+-------------------------+ +----------------------------+
v v
[ Database ] [ Downstream service ]
Each request runs on its own virtual thread that unmounts from a small set of carrier threads whenever it blocks, so the JDBC and HTTP client connection pools become the real concurrency limits.
Who should use virtual threads in a Spring Boot service?
Virtual threads are a good fit if your service matches most of these conditions:
- It runs on the servlet stack. It uses Spring MVC on embedded Tomcat, with blocking clients such as JDBC, JPA,
RestTemplateorRestClient. - Requests spend most of their time waiting. A typical handler calls a database, a cache or another service and waits for the response. It does not spend that time computing.
- Thread count is the limit you hit today. Under load, Tomcat's request threads are all busy while CPU stays low. You may have raised
server.tomcat.threads.maxrepeatedly to get more concurrency. - You can run a JDK with virtual threads. That means JDK 21 or later, together with a Spring Boot release that supports the
spring.threads.virtual.enabledproperty.
They are a poor fit in these cases:
- The service is mostly CPU-bound. Adding threads does not add cores.
- The service is already built on WebFlux. It already avoids blocking threads, so there is little left for virtual threads to fix.
- The service depends on libraries that pin carriers and that you cannot upgrade or replace. The sections on pinning and on when to avoid virtual threads cover these cases in detail.
In practice, the main audience is teams that maintain conventional blocking REST APIs. These teams want more concurrency per instance but do not want the cost of a reactive rewrite.
How do virtual threads work under the hood?
A virtual thread is a java.lang.Thread whose stack the JVM does not tie to an OS thread. When it runs, the JVM mounts it on a carrier, which is an ordinary platform thread. When it reaches a blocking operation that the JDK supports, the JVM unmounts it. The thread's stack frames are copied to the heap as a continuation, and the carrier goes back to the scheduler.
The pieces involved are:
- The scheduler. By default the JDK schedules virtual threads on a work-stealing
ForkJoinPooldedicated to them. Its parallelism defaults to the number of available processors, which is why the carrier count roughly matches the core count. The system propertyjdk.virtualThreadScheduler.parallelismcan override it, but most services should leave the default in place. - JDK blocking operations that support unmounting. The JDK reimplemented networking in
java.netandjava.nio.channels, the locks injava.util.concurrent,Thread.sleep, and similar operations. When a virtual thread blocks in one of these, it parks instead of holding the OS thread. JDBC drivers and HTTP clients built on JDK sockets inherit this behaviour. - Operations that cannot unmount. Some operations block the carrier instead, including many file system calls. For some of these, the JDK temporarily adds a carrier to compensate. Others pin the carrier, which the pinning section covers.
- Creation APIs. You rarely create virtual threads by hand in Spring Boot. When you do, the standard entry points are
Thread.ofVirtual()andExecutors.newVirtualThreadPerTaskExecutor().
Setting spring.threads.virtual.enabled=true tells Spring Boot to use virtual-thread-based executors in the places it controls. Those places are Tomcat's request handling and the auto-configured task executor and scheduler. Your controller code is unchanged. It runs on a different kind of thread and makes the same blocking calls, and the JVM takes care of parking and resuming it.
How do you enable virtual threads in Spring Boot and verify they are active?
The switch is one property: set spring.threads.virtual.enabled=true in application.properties or application.yml, running on a JDK that supports virtual threads. Spring Boot then configures the embedded Tomcat to handle each request on a new virtual thread instead of a pooled platform thread. It also reconfigures the auto-configured task executor and task scheduler, so @Async methods and @Scheduled tasks move over too. Coverage of other components has changed between releases, so check the Spring Boot documentation for your version to see which ones switch.
Do not assume the property took effect. Add a temporary endpoint that logs Thread.currentThread().isVirtual() along with Thread.currentThread().toString(). Log toString() rather than getName(), because virtual threads are often unnamed and getName() can return an empty string. When the property is working, toString() shows a VirtualThread identifier and the carrier thread it is mounted on.
Then check the other execution paths with the same logging:
@Asyncmethods: Log from inside the method body. If your application defines its ownTaskExecutorbean, Spring Boot's auto-configuration backs off, and those methods keep running on whatever pool you defined.@Scheduledtasks: Log from inside the task. A customTaskSchedulerbean has the same effect and keeps scheduled work off virtual threads.
This step matters because one hand-written executor bean can quietly keep part of the service on platform threads.
The work is small: one property and a few log lines, with no change to your controllers or the blocking client code they call. Moving the same service to a reactive stack would mean rewriting request handling, data access and error handling, and retraining the team to debug asynchronous code.
// Requires spring.threads.virtual.enabled=true and a JDK with virtual threads (21+).
// Temporary diagnostics: remove once you have confirmed where each path runs.
package com.example.demo;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.context.annotation.Configuration;
import org.springframework.scheduling.annotation.*;
import org.springframework.stereotype.Service;
import org.springframework.web.bind.annotation.*;
@Configuration @EnableAsync @EnableScheduling
class ThreadCheckConfig {}
@Service
class ThreadProbe {
private static final Logger log = LoggerFactory.getLogger(ThreadProbe.class);
// toString() not getName(): virtual threads are often unnamed.
static String describe() {
Thread t = Thread.currentThread();
return "virtual=" + t.isVirtual() + " thread=" + t;
}
@Async // Logs the executor actually used; a custom TaskExecutor bean overrides it
public void asyncCheck() { log.info("@Async {}", describe()); }
@Scheduled(fixedDelay = 60_000) // A custom TaskScheduler bean keeps this off virtual threads
public void scheduledCheck() { log.info("@Scheduled {}", describe()); }
}
@RestController
class ThreadCheckController {
private static final Logger log = LoggerFactory.getLogger(ThreadCheckController.class);
private final ThreadProbe probe;
ThreadCheckController(ThreadProbe probe) { this.probe = probe; }
@GetMapping("/debug/thread")
String check() {
String info = ThreadProbe.describe(); // Tomcat request thread
log.info("request {}", info);
probe.asyncCheck();
return info;
}
}
A temporary endpoint, @Async method and @Scheduled task that each log Thread.isVirtual() and Thread.toString(), so you can confirm that request handling, async execution and scheduling all run on virtual threads after setting spring.threads.virtual.enabled=true.
How can virtual threads save engineering time?
The savings come from work you no longer have to do. Faster code is not the source.
- No reactive rewrite. Without virtual threads, the usual way to get more concurrency on blocking I/O is to move to WebFlux and reactive drivers. That touches every controller, repository and error handler. With virtual threads, you keep the existing code and change configuration.
- Less thread-pool tuning. You no longer need to keep re-sizing
server.tomcat.threads.max, or maintain several hand-tuned executors for different call types, to stay ahead of load. The tuning effort moves to connection pools and bulkheads. These map directly to real capacity, so they are easier to reason about. - Readable stack traces and normal debugging. Each request is still one thread running sequential code. Exceptions show the full call path, breakpoints behave as expected, and new team members do not need to learn operator chains or reactive context propagation.
- Simpler fan-out. To call several services in parallel, you can submit blocking calls to
Executors.newVirtualThreadPerTaskExecutor()and wait on the results. You do not need to composeCompletableFuturecallbacks or size a dedicated pool for that call path. - Less code to maintain. Custom executors that existed only to work around thread scarcity can often be deleted after the audit described in the rollout section.
Illustrative estimate (assumed inputs, not a measured result). Assume a service has 40 endpoints. Assume a reactive migration would take about 4 hours per endpoint for code, tests and review, plus 40 hours of shared work on drivers, error handling and team ramp-up. That comes to 40 × 4 + 40 = 200 hours. Assume the virtual-thread path takes the 30-hour audit estimated in the rollout section below, plus about 10 hours of load testing, for 40 hours in total. Under these assumptions, the difference is about 160 hours. Your own inputs will differ, so substitute your endpoint count and per-item effort before using this to plan.
Why does Tomcat max-threads stop being the bottleneck?
With platform threads, Tomcat's request thread pool is the first limit a request reaches. When all threads are busy, new requests wait in the accept queue, and the database and downstream services are protected because of that cap. Once each request gets its own virtual thread, the cap is gone. Every incoming request starts work immediately, and the waiting moves to the next scarce resource it needs. In most blocking services, that resource is a connection pool.
Connections are now the bottleneck because a virtual thread blocked on a JDBC call still holds a physical connection for the whole call. A connection serves one request at a time, so creating more threads only lengthens the queue for it.
Illustrative estimate. Assume each request spends 50 ms waiting on the database and the JDBC pool holds 20 connections. One connection completes about 1,000 ms ÷ 50 ms = 20 requests per second. Twenty connections give a ceiling of about 400 requests per second. This holds with 200 virtual threads or 200,000. Above that rate, requests wait for a free connection until they hit the pool's acquisition timeout.
| Resource | Platform threads | Virtual threads |
|---|---|---|
| Tomcat request threads | Usually the first limit | Effectively unlimited |
| JDBC connection pool | Rarely saturated | Usually the first limit |
| HTTP client connection pools | Shielded by the thread cap | Exhausted under bursts |
| Downstream rate limits | Rarely reached | Reached quickly, returns throttling errors |
The same applies to outbound HTTP client pools and to quotas enforced by other teams' services. Virtual threads do not add capacity. They remove the cap that was hiding the real limits.
How should you bound concurrency once thread pools no longer do it?
Previously, a 200-thread Tomcat pool meant at most 200 requests could be waiting on the 20-connection database pool at once. With virtual threads, ten thousand requests can each take a virtual thread and queue for those same 20 connections. The database is no more loaded than before, but every queued request holds memory, an open socket and a client's patience. When the pool's acquisition timeout fires, a burst of failures arrives at the same moment. Callers retry, and you have swapped thread exhaustion for a timeout storm.
The fix is to put the cap back on purpose, at the scarce resource rather than on the request thread. A java.util.concurrent.Semaphore sized to the resource's real capacity works well. Call tryAcquire with a short timeout before calling the database or a downstream service, and release the permit in a finally block. If no permit is available within the timeout, fail fast with a 503 or 429. Don't let the request join an unbounded wait.
This is the bulkhead pattern. Give each dependency its own permit budget, so a slow payment provider exhausts only its own permits and doesn't block requests that only need the cache. Set the semaphore timeout shorter than the connection pool's acquisition timeout, so rejection happens at the place you control.
Dashboards also need to change. Active and busy thread counts no longer indicate saturation. Track these instead:
- Connection pool wait time
- Permits in use
- Permit rejections per dependency
import java.util.concurrent.Semaphore;
import java.util.concurrent.TimeUnit;
import java.util.function.Supplier;
import org.springframework.http.HttpStatus;
import org.springframework.stereotype.Component;
import org.springframework.web.server.ResponseStatusException;
@Component
public class PaymentBulkhead {
// Sized to the payment provider's real capacity, not to incoming request volume.
private static final int MAX_CONCURRENT = 20;
// Fair ordering so waiting requests are served roughly first-come, first-served.
private final Semaphore permits = new Semaphore(MAX_CONCURRENT, true);
public <T> T call(Supplier<T> work) {
boolean acquired;
try {
// Keep this shorter than the connection pool's acquisition timeout,
// so overload is rejected here, where we control it.
acquired = permits.tryAcquire(200, TimeUnit.MILLISECONDS);
} catch (InterruptedException e) {
Thread.currentThread().interrupt();
throw new ResponseStatusException(HttpStatus.SERVICE_UNAVAILABLE, "interrupted");
}
if (!acquired) {
// Fail fast instead of letting virtual threads pile up behind the dependency.
throw new ResponseStatusException(HttpStatus.SERVICE_UNAVAILABLE, "payment bulkhead full");
}
try {
return work.get();
} finally {
permits.release(); // Always return the permit, even on failure.
}
}
// Feed this to a gauge: permits in use is the saturation signal now, not thread count.
public int permitsInUse() {
return MAX_CONCURRENT - permits.availablePermits();
}
}
A per-dependency Semaphore bulkhead that waits briefly for a permit, rejects with 503 when the payment provider's budget is exhausted, always releases the permit in a finally block, and reports permits in use for monitoring.
What is thread pinning and how do you detect and fix it?
A virtual thread is pinned when it blocks but cannot unmount from its carrier platform thread. The carrier stays occupied for the full duration of the blocking call, so for that time the virtual thread behaves like an ordinary platform thread. Two causes matter in practice:
- Native or foreign frames on the stack, such as JNI calls or foreign function upcalls.
synchronizedblocks or methods that block while holding a monitor. This applies on some JDK releases.
Newer JDKs have reduced the synchronized case. Check how the specific JDK you deploy behaves rather than assuming it is fixed or still broken.
Pinning is dangerous because it fails silently. The carrier pool is small, roughly one carrier per core by default. A few pinned threads blocked on slow I/O can occupy every carrier. When that happens, unrelated requests stop making progress, CPU sits idle, and the service looks hung. Light load tests rarely reproduce this, because carriers free up before anyone notices.
Detecting pinning
- Enable JDK Flight Recorder and watch the
jdk.VirtualThreadPinnedevent. It records stack traces for pinned blocking that exceeds a duration threshold. - Capture thread dumps that include virtual threads, for example with
jcmd <pid> Thread.dump_to_file. Look for many threads parked inside monitors or native frames. - Correlate the pinned stacks with long blocking I/O. A pinned socket read is the main problem. Brief pinning around an in-memory operation usually is not.
Fixing it
- On JDKs that still pin on monitors, replace
synchronizedthat guards blocking I/O withReentrantLock. - Audit JDBC drivers, connection pools, and HTTP clients for internal synchronization, because that is where most pinning originates.
- Often the real fix is a dependency upgrade. Many libraries have already removed this synchronization in later releases.
import java.io.IOException;
import java.io.InputStream;
import java.net.Socket;
import java.util.concurrent.locks.ReentrantLock;
// Serializes access to a shared, non-thread-safe socket connection.
public class LegacyGatewayClient {
private final Socket socket;
private final ReentrantLock lock = new ReentrantLock();
public LegacyGatewayClient(Socket socket) {
this.socket = socket;
}
// BEFORE: on JDKs that pin on monitors, a virtual thread blocked in
// read() here keeps its carrier occupied for the whole read.
public synchronized int readHeaderPinned() throws IOException {
InputStream in = socket.getInputStream();
return in.read(); // blocking socket I/O while holding a monitor
}
// AFTER: ReentrantLock lets the virtual thread unmount while it waits
// for the lock and while it blocks on the socket read.
public int readHeader() throws IOException {
lock.lock();
try {
InputStream in = socket.getInputStream();
return in.read();
} finally {
lock.unlock(); // always release, even if read() throws
}
}
}
Replacing a synchronized method that guards blocking socket I/O with a ReentrantLock, so virtual threads can unmount from their carrier on JDKs that still pin on monitors.
When should you avoid virtual threads, and what are the alternatives?
Some workloads gain nothing from virtual threads, and a few get worse.
CPU-bound endpoints. Virtual threads speed up waiting. They do not speed up computing. The scheduler runs virtual threads on a small carrier pool sized to the number of cores. A burst of heavy requests, such as image resizing, large JSON transforms or cryptography, can occupy every carrier. Requests that only need to wait on I/O then cannot get scheduled. Send that work to a separate bounded platform-thread executor.
ThreadLocal-heavy code. MDC and the security context still work, because they are scoped to one request. Per-thread caches and object pools stop paying off, because each virtual thread is short-lived and new, so nothing gets reused. With very large thread counts, every ThreadLocal value is copied many times and memory use multiplies.
Libraries you cannot patch. A closed-source driver that blocks in native code, or holds monitors during I/O, will pin carriers. You may have no fix short of replacing the library.
| Option | Strength | Weakness |
|---|---|---|
| Virtual threads | Blocking code scales cheaply | No backpressure; pinning risk |
| Tuned platform pools | Predictable; pool size limits concurrency | Thread count limits throughput |
| WebFlux / reactive | Streaming, fine-grained flow control, backpressure | Rewrite cost; harder debugging |
Virtual threads are also not structured concurrency. They do not tie subtasks to a parent's lifetime or cancel siblings when one fails. On their own they provide no backpressure, so the bounds described in the section on bounding concurrency remain your job.
How do you roll out virtual threads and measure the impact on cost and risk?
Treat the switch as an experiment with a control. Run the same build twice under identical load: once with the existing platform-thread configuration, once with virtual threads enabled. Downstream calls must have realistic latency, including slow tails. With instant mocks, both configurations look the same because no thread is held long enough to matter.
| Metric | What to watch | Why it matters |
|---|---|---|
| p99 latency | Tail under peak load | Virtual threads mostly help when requests queue for a free thread |
| Error rate | Timeouts, connection-pool exhaustion | Contention moves from Tomcat to JDBC or HTTP client pools |
| Pool wait time | Time spent acquiring a connection | Rising wait time means a downstream bound is now the limit |
| Heap use | Peak and GC frequency | More concurrent requests keep more request state alive at once |
Ship the change behind an externally set configuration property. Enable it on one canary instance, compare its metrics with the rest of the fleet, then widen the rollout. Reverting should require only a config change and a restart, not a rebuild.
The code change is small. Most of the work is the audit of executors, pinning-prone synchronized blocks around I/O, and ThreadLocal caches.
Illustrative estimate (assumed numbers, not a benchmark): audit hours = (custom pools + ThreadLocal sites + synchronized-I/O sites) × hours per item = (6 + 10 + 4) × 1.5 = 30 hours, against roughly an hour for the configuration change itself.
Results depend on your JDK and Spring Boot versions, because pinning behaviour and framework support have changed between releases. Verify against your own stack rather than relying on published results.
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.