What are virtual threads and how does Project Loom work?
A virtual thread is a java.lang.Thread that the JVM schedules, not the operating system. Project Loom's design keeps the familiar thread API but separates the logical thread from the OS thread that runs it. A small pool of platform threads, called carriers and typically sized to the number of CPU cores, runs many virtual threads.
When a virtual thread hits a supported blocking operation, such as a socket read while a JDBC driver waits for a query result, the JVM unmounts it. The thread's stack is saved to the heap and the carrier is free to run another virtual thread. When the data arrives, the virtual thread is remounted, possibly on a different carrier, and continues from where it stopped.
This is why plain blocking code scales without a reactive rewrite. A thread-per-request handler that calls executeQuery() stays the same. The waiting now costs a little heap memory instead of a whole OS thread, so you can have tens of thousands of requests in flight.
requests (VTs) carriers (~cores) connection pool database
VT VT VT VT VT --> [C1][C2][C3][C4] --> [conn x N] -------> [DB]
^ ^
unmounted VTs park here queuing moves here:
(cheap, on heap) VTs wait for a free connection
The exception is pinning. In some cases a virtual thread cannot unmount, for example while running native code or, on older JDKs, inside a synchronized block. A pinned thread holds its carrier for the entire blocking call. If enough threads pin, the carrier pool runs out and throughput falls back to platform-thread levels.
Requests: one virtual thread (VT) each, tens of thousands in flight
+----+ +----+ +----+ +----+ +----+ +----+ +----+ +----+
| VT | | VT | | VT | | VT | | VT | | VT | | VT | | VT | ...
+----+ +----+ +----+ +----+ +----+ +----+ +----+ +----+
| | | | | | | |
+------+------+------+--+---+------+------+------+
| mount when runnable
v
+------------------------------------+ unmount +------------------+
| Carrier platform threads (~cores) |----------->| Parked VTs |
| +----+ +----+ +----+ +----+ | (blocked | stacks on heap, |
| | C1 | | C2 | | C3 | | C4 | | on I/O) | carrier is freed |
| +----+ +----+ +----+ +----+ |<-----------| until I/O ready |
+------------------------------------+ remount +------------------+
| (any carrier)
| getConnection()
v
+------------------------------------+
| JDBC connection pool (N conns) |
| QUEUE: VTs wait here for a free |
| connection (parked, not pinned) |
+------------------------------------+
|
| executeQuery() -> socket read: VT unmounts
v
+------------------------------------+
| Database |
+------------------------------------+
Pinned VT (native code; synchronized on older JDKs) cannot unmount
and holds its carrier for the whole blocking call.
Virtual threads mount on a few carrier threads, park cheaply on the heap while blocked on I/O, and queue for the bounded JDBC connection pool, which becomes the real concurrency limit unless pinning exhausts the carriers first.
How do you enable virtual threads in Spring Boot, and what actually changes?
Switching a Spring Boot application to virtual threads is one property: spring.threads.virtual.enabled=true. You need a recent Spring Boot release and a JDK where virtual threads are a final feature. With the flag set, the embedded servlet container runs each request on a new virtual thread instead of drawing from its bounded worker pool. The auto-configured applicationTaskExecutor, which backs @Async methods, and the auto-configured task scheduler also create virtual threads. Your controllers, services and repositories stay the same. Code that blocks on a JDBC call now blocks a virtual thread, and the JVM unmounts it from its carrier while it waits.
That low cost makes the flag cheap to try. It also makes it easy to assume more changed than did. The property only affects executors that Spring Boot creates for you. If you define your own ThreadPoolTaskExecutor bean, that bean replaces the auto-configured one and keeps platform threads. Any Executors.newFixedThreadPool(...) call in application code also keeps platform threads. So do the internal threads of third-party libraries such as messaging clients, HTTP clients and connection-pool housekeepers. Request handling may move to virtual threads while an @Async path you depend on still queues behind a fixed pool of 20.
Check at runtime rather than reading configuration. Log Thread.currentThread().isVirtual() alongside the thread's toString() at the entry point of each execution path: controllers, @Async methods, scheduled jobs and message listeners. Search the codebase for Executors.new and for executor bean definitions. Treat every hit as a pool you need to deliberately migrate or deliberately keep.
// application.properties: spring.threads.virtual.enabled=true
// Requires a JDK where virtual threads are final (21+) and a Boot release that supports the flag.
package com.example.probe;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.scheduling.annotation.Async;
import org.springframework.scheduling.annotation.Scheduled;
import org.springframework.stereotype.Service;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
// Assumes @EnableAsync and @EnableScheduling are on a configuration class.
final class ThreadProbe {
private static final Logger log = LoggerFactory.getLogger(ThreadProbe.class);
// Log the path name, whether it is virtual, and the thread's toString()
// (which shows the pool or carrier), so each execution path is verified, not assumed.
static void report(String path) {
Thread t = Thread.currentThread();
log.info("path={} virtual={} thread={}", path, t.isVirtual(), t);
}
}
@RestController
class ProbeController {
private final ReportService reports;
ProbeController(ReportService reports) { this.reports = reports; }
@GetMapping("/probe")
String probe() {
ThreadProbe.report("http-request"); // servlet container thread
reports.buildAsync();
return "ok";
}
}
@Service
class ReportService {
// Virtual only if no custom ThreadPoolTaskExecutor bean replaced the auto-configured one.
@Async public void buildAsync() { ThreadProbe.report("async"); }
@Scheduled(fixedDelay = 60_000) public void sweep() { ThreadProbe.report("scheduled"); }
}
With spring.threads.virtual.enabled=true set, a small probe logs Thread.currentThread().isVirtual() at the request, @Async and @Scheduled entry points so you can confirm which paths actually moved to virtual threads.
Where does the bottleneck move for JDBC workloads?
With a platform thread per request, the server's thread pool was an implicit throttle: no more requests could run than there were threads, and the rest waited in the accept queue. With virtual threads, that ceiling is gone. Thousands of requests can be in flight at once, but the connection pool still has a fixed size. Requests now park while waiting to acquire a connection rather than waiting for a server thread. Throughput is capped by pool size and by what the database can actually execute.
Little's Law makes the limit concrete. The average number of connections in use equals the arrival rate multiplied by the average time each request holds a connection.
Illustrative estimate
Assumed inputs:
- Request rate: 1,200 requests per second reach code paths that use the database.
- Connection hold time: 40 ms on average, measured from acquisition to release. This includes queries, transaction overhead and any work done while the transaction is still open.
Connections needed = 1,200 × 0.040 = 48 connections on average. You also need headroom for bursts and variance.
If the pool has 30 connections, adding virtual threads will not raise throughput. It only lengthens the wait queue in front of the pool, and acquisition timeouts become your new failure mode.
The tempting fix is to enlarge the pool. That moves the contention into the database itself, which then has to handle more concurrent sessions, lock waits, memory per connection and CPU scheduling. Past the database's saturation point, a bigger pool increases hold time, and by Little's Law that raises the number of connections you need.
Virtual threads raise concurrency, not database throughput. The levers that actually help are:
- shorter hold times
- fewer queries per request
- keeping slow non-database work outside open transactions
What is JDBC pinning and how do you detect it?
A virtual thread is pinned when it blocks but cannot unmount from its carrier platform thread. The carrier stays occupied for the whole wait. Pinning always happens when the thread blocks inside native frames, such as a JNI call. On some JDK releases it also happens when the thread blocks while holding a monitor in a synchronized block or method. Newer releases have removed most of the synchronized case, so check how your runtime behaves before you rewrite anything. The risk is that the carrier pool is small, usually sized to the core count. If a few dozen requests pin carriers while they wait on network I/O, every other virtual thread queues behind them, even though they are runnable.
The symptom is a latency cliff under load. p99 jumps sharply at a concurrency level where CPU is moderate, the database shows spare capacity, and the connection pool is not exhausted. Throughput flattens while every resource dashboard looks healthy.
To confirm pinning, record with JDK Flight Recorder and look for jdk.VirtualThreadPinned events. Each event includes a stack trace that shows where the pin happened and how long it lasted. For a snapshot, use jcmd <pid> Thread.dump_to_file -format=json <file>. Unlike older dump formats, it includes virtual threads, so you can see which ones are parked on a monitor and what they hold.
Check these places first:
- JDBC drivers that guard socket reads with
synchronized - Connection pools that use synchronized sections or native calls
- Logging appenders and caches that take monitors around blocking writes
#!/usr/bin/env bash
# Capture pinning evidence from a running Spring Boot JVM while it is under load.
# Run this during the latency cliff, not after it, so the events reflect the problem.
set -euo pipefail
PID="${1:?usage: $0 <java-pid>}" # e.g. from: jcmd -l
OUT="/tmp/pinning-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$OUT"
# 1. Start a time-boxed JFR recording. The built-in 'profile' settings enable
# jdk.VirtualThreadPinned with a duration threshold, so only longer pins are recorded.
jcmd "$PID" JFR.start name=pinning settings=profile duration=60s filename="$OUT/pinning.jfr"
# 2. Mid-recording, take a thread dump that includes virtual threads.
# The JSON format lists virtual threads with their stacks, so you can see
# which ones are blocked on a monitor and where.
sleep 30
jcmd "$PID" Thread.dump_to_file -format=json "$OUT/threads.json"
# 3. Wait for the recording to finish and be written to disk.
sleep 35
# 4. Check whether any pinning events were recorded at all.
jfr summary "$OUT/pinning.jfr" | grep -i VirtualThreadPinned || echo "no pinning events recorded"
# 5. Print each pinning event with a deep enough stack to reach the driver,
# pool or logging frame that held the monitor or entered native code.
jfr print --events jdk.VirtualThreadPinned --stack-depth 30 "$OUT/pinning.jfr" \
> "$OUT/pinned-events.txt"
echo "Pinned stacks: $OUT/pinned-events.txt"
echo "Thread dump: $OUT/threads.json"
Records JFR pinning events and a JSON thread dump that includes virtual threads from a running JVM under load, then extracts the pinned stack traces so you can trace each pin to a driver, pool or appender frame.
How do you add backpressure once the thread-pool limit is gone?
With a platform thread pool, the server's maximum thread count capped how many requests could touch the database at once. Virtual threads remove that cap. A traffic spike now becomes thousands of concurrent callers waiting on a pool of a few dozen connections, and the waiting moves somewhere you may not be watching.
Make connection acquisition the deliberate limit
The pool's connection-acquisition timeout is now your main backpressure mechanism. A long default lets requests pile up silently until clients time out first. Set the timeout close to your latency budget so that excess load fails fast with a clear error, which you can map to a 503 at the edge, instead of building an unbounded queue.
Add explicit limits
Put a semaphore or bulkhead around database access and around each outbound dependency, and size it to what that dependency can sustain. The code example below shows a semaphore guarding a repository call. It uses tryAcquire with a short timeout and rejects the request when no permit is available, so overload is turned away before it reaches the database.
Context and ThreadLocals
MDC, transaction context and security context still work, because each virtual thread has its own ThreadLocals. Heavy ThreadLocal use multiplied across many virtual threads costs memory. Per-thread object pooling also stops paying off: virtual threads are not reused, so each pooled object is created once and then discarded.
Observability
Thread-count metrics and traditional thread dumps tell you less than before. Dashboards should track three things instead: connection-acquisition wait time, in-flight requests per bulkhead, and pinning events.
package com.example.orders;
import java.util.Optional;
import java.util.concurrent.Semaphore;
import java.util.concurrent.TimeUnit;
import org.springframework.http.HttpStatus;
import org.springframework.stereotype.Service;
import org.springframework.web.server.ResponseStatusException;
@Service
public class OrderLookupService {
// Set below the connection pool size (e.g. pool of 30) so other work keeps headroom.
private static final int MAX_CONCURRENT_DB_CALLS = 20;
private final Semaphore dbPermits = new Semaphore(MAX_CONCURRENT_DB_CALLS, true);
private final OrderRepository orders;
public OrderLookupService(OrderRepository orders) { this.orders = orders; }
// Not @Transactional: take the permit before a connection is acquired.
public Optional<Order> findOrder(long id) {
boolean acquired = false;
try {
// Wait briefly, then shed load at the edge instead of queueing without bound.
acquired = dbPermits.tryAcquire(50, TimeUnit.MILLISECONDS);
if (!acquired) {
throw new ResponseStatusException(HttpStatus.SERVICE_UNAVAILABLE, "Database busy, retry later");
}
return orders.findById(id);
} catch (InterruptedException e) {
Thread.currentThread().interrupt();
throw new ResponseStatusException(HttpStatus.SERVICE_UNAVAILABLE, "Interrupted waiting for DB permit");
} finally {
if (acquired) dbPermits.release();
}
}
// Register as a gauge so dashboards show in-flight calls for this bulkhead.
public int inFlight() { return MAX_CONCURRENT_DB_CALLS - dbPermits.availablePermits(); }
}
A fair Semaphore caps concurrent repository calls. It waits at most 50 ms for a permit and otherwise rejects the request with a 503, and it exposes an in-flight count for metrics.
When should you avoid virtual threads, and what are the alternatives?
Virtual threads remove the cost of waiting. They do nothing for work that is not waiting. If the database is already at its CPU or I/O ceiling, more concurrent callers only lengthen its queues. The same is true when the connection pool is the binding constraint by design: requests that once queued for a platform thread now queue for a connection, and latency barely moves.
CPU-bound handlers are a worse fit. The scheduler does not time-slice virtual threads. A thread that computes without blocking holds its carrier until it finishes. A few hashing or serialization-heavy requests can occupy every carrier and stall I/O-bound requests that are ready to run. Keep that work on a bounded platform-thread executor.
Some libraries assume a small, stable set of threads. Per-thread object pools and ThreadLocal caches multiply memory when each request gets its own thread, and they never get reused. Some instrumentation agents and profilers also behave unevenly with very large virtual-thread counts, so test your tooling under realistic load before relying on it.
| Tuned platform-thread pool | Virtual threads | Reactive non-blocking stack | |
|---|---|---|---|
| Code changes | None | Minimal, mostly configuration | Rewrite to async types and drivers |
| Migration cost | Low | Low to moderate (pinning audit) | High |
| Backpressure | Implicit via pool size | Explicit: semaphores, pool limits | Built into the stream protocol |
| Debuggability | Familiar stack traces | Familiar traces, uneven tooling at scale | Fragmented async traces |
| Best fit | CPU-bound or modest concurrency | High-concurrency blocking I/O | Streaming, end-to-end non-blocking I/O |
A service that is already non-blocking end to end gains nothing from switching. It has no blocked threads to make cheap.
Who benefits from virtual threads? A decision checklist
Run through these before changing anything. If most answers are "yes," virtual threads are likely worth a trial.
- Request threads mostly wait. Profiles or thread dumps show request threads parked in socket reads to the database or downstream HTTP calls. They are not burning CPU.
- Thread-pool exhaustion is the observed limit. Requests queue for a worker thread while CPU, connection pool and database load all stay moderate.
- The database has headroom. If the database is already saturated, more concurrent callers only lengthen its queue.
- Your drivers and libraries are pinning-safe, or you can audit them.
The main payoff is engineering time. A reactive rewrite changes every signature, every test and every stack trace in the service. Virtual threads keep the imperative code your team already debugs well. The cost moves elsewhere:
| Area | Reactive rewrite | Virtual threads |
|---|---|---|
| Application code | Rewritten to non-blocking APIs | Largely unchanged |
| Driver requirements | Non-blocking drivers | Existing JDBC drivers, after a pinning audit |
| Capacity tuning | Event-loop sizing | Connection pool and semaphore resizing |
| Observability | New tracing and context propagation | New dashboards for pool wait time and pinned threads; check that profilers and APM agents handle virtual threads |
Validation plan
Load-test the same scenario twice, once with the setting off and once with it on, at concurrency above the current pool size. Compare p99 latency, timeout and error rates, and connection-pool wait time, not just average throughput. Averages can improve while the tail gets worse as contention shifts to the database. Then roll out with spring.threads.virtual.enabled set per environment, so you can revert with a configuration change instead of a redeploy of different code.
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.