Virtual Threads & Structured Concurrency

Use Thread.startVirtualThread(runnable) to create and start one immediately, Thread.ofVirtual().start(runnable) for the same via a builder, .unstarted(runnable) to build without starting, or Executors.newVirtualThreadPerTaskExecutor() to get one virtual thread per submitted task.

ThreadLocal data is mutable and lives until you manually remove it, which is easy to forget and wastes memory — bad when you have millions of virtual threads. ScopedValue is immutable, has a clear bounded lifetime, and cleans itself up automatically, so it is cheaper and safer.

Open the scope (usually in try-with-resources). fork() starts each subtask and returns a handle without blocking. join() waits for all subtasks to finish. After join, get() reads a successful subtask's result. close() (automatic) shuts the scope and waits for everything to stop.

The virtual thread pauses and unmounts from its carrier (the platform thread running it), freeing that carrier to run other virtual threads. When the blocking call is ready to continue, the virtual thread is remounted and resumes. The carrier is never wasted just waiting.

Virtual threads are cheap and disposable, so you create a fresh one per task instead of reusing them from a pool. Pooling exists to reuse expensive resources; virtual threads aren't expensive, so a pool only adds a bottleneck. Use Executors.newVirtualThreadPerTaskExecutor().

Virtual threads shine for I/O-bound work — tasks that spend most of their time waiting on the network, disk, or other services. For CPU-bound work they give no benefit, because the real limit is the number of CPU cores, not the number of threads.

Regular Java threads map one-to-one to OS threads, which are expensive and limited, so you can only have a few thousand. Virtual threads are cheap, so you can have millions and write simple blocking code that scales.

Pinning is caused by blocking inside a synchronized block/method (on older JDKs) and inside native/JNI calls. Ordinary blocking like socket I/O, Thread.sleep, BlockingQueue, and ReentrantLock do NOT pin—the virtual thread unmounts normally.

Pinning is when a virtual thread can't detach from its OS carrier thread while it blocks, so it keeps that carrier busy. That wastes a scarce carrier and can stall other virtual threads, hurting throughput.

ShutdownOnFailure (fan-out, need all): the moment any subtask fails, the scope cancels the rest and the failure is surfaced — use it when you need every result. ShutdownOnSuccess (race, need one): the first success cancels the rest — use it when any one winner is enough.

A virtual thread doesn't have its own OS thread. To run, the JVM mounts it onto a carrier (a real platform thread). When it blocks, the JVM unmounts it and stores its stack on the heap, freeing the carrier for other virtual threads.

Replace blocking synchronized blocks/methods with java.util.concurrent.locks.ReentrantLock using lock()/unlock() in a try/finally. ReentrantLock lets the virtual thread unmount while it waits, so the carrier stays free. Also keep critical sections short and avoid blocking inside them.

A ScopedValue is a way to share a fixed piece of data with code called inside a block, without passing it as a parameter. You bind it with ScopedValue.where(KEY, value).run(task); inside that task, KEY.get() returns the value. Outside, it is unbound.

Use Thread.ofVirtual().start(...) or Executors.newVirtualThreadPerTaskExecutor(). They're cheap because a virtual thread doesn't reserve a big OS-thread stack — its stack lives on the heap and grows as needed, so millions fit.

Use .run() when the task returns nothing and throws only unchecked exceptions; use .call() when the task returns a value or throws a checked exception. Common mistakes: reading the value outside the scope (throws NoSuchElementException) and expecting the binding to outlive the run/call call.

Thread.ofVirtual() returns a Thread.Builder you can configure — set a name (optionally with an auto-incrementing counter), an uncaught-exception handler, thread-local inheritance — then call .start(runnable) to run it or .unstarted(runnable) to get it ready but not started. Prefer it over startVirtualThread when you need that configuration or a Thread reference before it runs.

You can't change a bound value; instead you open a new nested binding with where() around the inner code. The inner value applies only inside that nested block and the outer value is restored when it ends. This keeps data flow predictable and stack-structured.

When you fork subtasks inside a structured-concurrency scope, those subtasks automatically see the scoped values bound in the parent. You don't pass them in — the bindings are inherited because the subtasks run within the parent's bounded scope, and they're shared, not copied.

Errors flow up: a failing subtask can shut the scope down and surface to the parent. Cancellation flows down: shutting down interrupts the children. But interruption is cooperative — a subtask only stops if it responds to interruption, e.g. by being in a blocking call or checking the interrupt flag.

The executor is an AutoCloseable ExecutorService, so try-with-resources closes it automatically at the end of the block. Closing initiates an orderly shutdown and blocks until all submitted tasks finish, so the block won't exit while work is still running.

Keep one virtual thread per request, but guard the downstream call with a Semaphore sized to what the API allows. Each thread acquires a permit before calling and releases it after, so only that many calls happen at once — without limiting how many threads exist.

Each virtual thread keeps its own copy of every ThreadLocal value. With millions of virtual threads, expensive per-thread values multiply into a lot of memory. So avoid large/mutable ThreadLocals; prefer ScopedValue for sharing read-only context.

Run with -Djdk.tracePinnedThreads to print a stack trace whenever a thread blocks while pinned (older JDKs), or record a JFR profile and look for jdk.VirtualThreadPinned events. Both show exactly where the pinning happens.

Use structured concurrency for a self-contained fan-out within one request, where you want clear lifetimes, automatic cancellation, and errors that surface to the caller. CompletableFuture suits long-lived async pipelines. The main risks: it's still a preview API and shines mainly with virtual threads.

Virtual threads help when many tasks spend most of their time blocked on I/O. They don't speed up CPU-bound work, can be undermined by pinning (synchronized/native code keeping the carrier busy), and break old assumptions like thread pooling and thread-local caching. Don't pool them and don't treat them as faster threads.

Stop pooling virtual threads — one per task. Limit concurrency at the downstream resource with semaphores, not by thread count. Use virtual threads only for I/O-bound work. Avoid heavy ThreadLocals and prefer ScopedValue. Watch for pinning on synchronized/native calls.

Virtual threads help concurrency for blocking/I/O-bound work, not raw CPU speed. They don't help CPU-bound tasks, and you can lose the benefit through pinning (e.g. blocking in synchronized) or by overloading a small downstream resource.

JEP 491 (JDK 24) reworked the runtime so a virtual thread can unmount even while holding a synchronized monitor, so synchronized no longer pins. Native/JNI blocking can still pin, and you must still watch carrier-pool sizing and thread-locals at scale.