Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Java 21 Virtual Threads: Syntax, Thread Pools, and Concurrency

How Java 21 virtual threads are created and scheduled, why they must never be pooled, and the pinning, ThreadLocal, and resource-limit problems that decide whether they help.

~4 min readJava
#Java#Virtual Threads#Concurrency#Java 21
Java 21 virtual threads streaming into a carrier pipe beside platform thread workers

Virtual threads in Java 21 are ordinary Thread instances that the JVM mounts onto a small pool of carrier threads only while they are running. When a virtual thread blocks on I/O, the JVM unmounts it and reuses the carrier for another virtual thread, so a request handler that waits on a socket no longer costs an OS thread.

Syntax: three ways to start a virtual thread

java
// 1. Runnable Thread t = Thread.ofVirtual().name("vt-", 0).start(() -> System.out.println("hello")); t.join(); // 2. Shorthand Thread.startVirtualThread(() -> System.out.println("hello")); // 3. Unchecked construction with a builder Thread.Builder.OfVirtual builder = Thread.ofVirtual() .name("worker-", 1) .unstarted(() -> System.out.println("hello")); Thread thread = builder.start();

The builder is the only place where configuration is possible: name prefixes, inheritInheritableThreadLocals(false), and an uncaught exception handler. There is no priority and no thread group. Virtual threads are always daemon threads; setPriority is ignored and getPriority always returns NORM_PRIORITY.

The thread-per-task executor

Executors.newVirtualThreadPerTaskExecutor() returns an executor that creates one new virtual thread per submitted task and never pools them. It is the intended way to run virtual threads at scale.

java
try (var executor = Executors.newVirtualThreadPerTaskExecutor()) { List<Future<String>> futures = new ArrayList<>(); for (String id : ids) { futures.add(executor.submit(() -> fetch(id))); } for (Future<String> f : futures) { results.add(f.get()); } }

The try-with-resources block calls close(), which is shutdown() plus awaitTermination() on Java 21, so the executor waits for every task before the block exits. Structured concurrency (preview in 21, StructuredTaskScope) formalizes the same idea: the parent does not finish before its children.

Platform vs virtual threads

AspectPlatform threadVirtual thread
BackingOne OS thread, ~1 MB stack reservedHeap-allocated stack chunks, few KB to grow
Cost per unitMilliseconds to create, megabytes of address spaceMicroseconds, a few hundred bytes to start
Practical countThousandsMillions
SchedulingOS schedulerJVM schedules onto a ForkJoinPool of carriers
Blocking I/OBlocks an OS threadUnmounts; carrier is reused
PoolingRequired, expensiveNever pool them; create per task
DaemonConfigurableAlways daemon
ThreadLocal costAcceptableMultiplied by thread count

Deep dive: what actually breaks in production

1. Blocking on synchronized pins the carrier

In Java 21, a virtual thread that blocks inside a synchronized block or method cannot unmount, because the monitor is tied to the carrier thread. The carrier is pinned, and if enough virtual threads pin, the scheduler runs out of carriers and throughput collapses.

java
// Pins the carrier for the duration of the call in Java 21 public synchronized String load(long id) { return remoteClient.fetch(id); // blocking I/O inside a monitor }

Use ReentrantLock around blocking work instead. It cooperates with the virtual thread scheduler, so the thread unmounts as it should.

java
private final ReentrantLock lock = new ReentrantLock(); public String load(long id) { lock.lock(); try { return remoteClient.fetch(id); } finally { lock.unlock(); } }

JDK 24 (JEP 491) removes monitor pinning, so this specific hazard disappears there. On Java 21 it is real: monitor contention across thousands of virtual threads shows up as carriers stuck in BLOCKED and a scheduler that stops making progress. Native or foreign function calls also pin, because the JVM cannot save a stack it does not control.

You can detect pinning by running with -Djdk.tracePinnedThreads=full, which prints a stack trace whenever a virtual thread blocks while pinned.

2. Pooling virtual threads defeats their purpose

A pool exists to amortize the cost of creating an OS thread and to cap concurrency. Virtual threads are cheap to create and have no reason to be capped by a pool; a fixed pool of virtual threads reintroduces the queueing behaviour you were trying to remove. Limit the resource that is actually scarce instead.

java
private final Semaphore dbPermits = new Semaphore(20); public String query(String sql) { dbPermits.acquireUninterruptibly(); try { return jdbc.query(sql); // at most 20 concurrent DB calls } finally { dbPermits.release(); } }

Here the executor stays unbounded, but the database connection pool stays protected. That is the correct layer for the limit: virtual threads should be limited by a downstream resource, never by a thread pool.

3. ThreadLocal memory blowup

A ThreadLocal value lives as long as the thread. With a pool of 200 platform threads, 200 copies of a 1 MB buffer is 200 MB. With 200,000 virtual threads, the same code is 200 GB. Frameworks that cache per-request state in ThreadLocal behave badly under virtual threads for exactly this reason.

java
// Dangerous: every virtual thread allocates its own buffer private static final ThreadLocal<byte[]> BUFFER = ThreadLocal.withInitial(() -> new byte[1 << 20]);

Prefer passing context as method arguments, or use ScopedValue (preview in Java 21) for immutable per-request context. If a dependency insists on ThreadLocal, keep the values small and remove them in a finally block.

4. File I/O and CPU work do not become faster

Virtual threads help when a task spends its time waiting on something the JVM can poll: sockets, Selector, LockSupport, Thread.sleep, most java.nio channel operations. Blocking file I/O on the default file system generally does not unmount the virtual thread, because there is no pollable completion mechanism behind it, so a thread doing file I/O still occupies a carrier.

CPU-bound work gains nothing either: there are only availableProcessors carriers by default (tunable with -Djdk.virtualThreadScheduler.parallelism), so a compute loop on a virtual thread runs as fast as, and no faster than, the same loop on a platform thread. Parallel streams and ForkJoinPool remain the tools for CPU saturation.

java
// Wrong tool: CPU-bound work on a virtual thread String hash = sha256(hugeByteArray); // Right tool: keep CPU work on the common pool var sum = IntStream.range(0, 1_000_000).parallel().map(this::expensive).sum();

Common mistakes

  • Assuming virtual threads make code concurrent. They only remove the cost of blocking. A single-threaded pipeline stays single-threaded.
  • Wrapping synchronized around network calls. The classic pinning bug on Java 21; replace with ReentrantLock or restructure the critical section.
  • Capping concurrency with a fixed virtual-thread pool. Use a Semaphore, a connection pool, or a bounded queue instead, sized to the downstream service.
  • Sharing heavy state through ThreadLocal. Cost per thread multiplies by the number of virtual threads; prefer explicit parameters or ScopedValue.
  • Leaving uncaught exceptions silent. A virtual thread with no handler dies quietly; set one on the builder, or collect results through Future/TaskScope so failures surface.
  • Expecting interrupts to stop work automatically. Interruption still requires cooperative checks; virtual threads do not change that contract.
  • Debugging with old habits. jcmd <pid> Thread.dump_to_file includes virtual threads and is the practical way to see them; a plain OS-level profiler sees only carriers.

The rule of thumb: virtual threads are for I/O-bound, thread-per-request code, one thread per task, no pooling, with every scarce resource behind an explicit limiter.

Try matching browser tools

All tools

Small utilities that fit Java work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Java guides

More in Java

All Java guides

The guides filed next to this one in Java, in library order.