Java Reference ยท Concurrency
Java virtual threads
Reference for Java virtual threads (final in Java 21): how to create them, how they differ from platform threads, per-task executors, pinning and limits.
A virtual thread is a Thread that is scheduled by the JVM instead of the operating system. Thousands or millions of them can exist at once because each one is just a small object on the heap. When a virtual thread blocks on something like Thread.sleep(), a socket read or a lock, the JVM unmounts it from its carrier (an ordinary platform thread) and runs another virtual thread there.
Virtual threads were finalized in Java 21. They let you write simple blocking code, one thread per request or task, without the memory cost of platform threads. They do not make CPU-bound code faster; they make waiting cheap.
Thread t = Thread.ofVirtual().name("worker").start(() -> System.out.println("hi")); t.join(); try (var executor = Executors.newVirtualThreadPerTaskExecutor()) { executor.submit(() -> System.out.println("task")); } // close() waits for submitted tasks
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.
Syntax
Thread.Builder.OfVirtual b = Thread.ofVirtual(); Thread startVirtualThread(Runnable task) // static shortcut ExecutorService Executors.newVirtualThreadPerTaskExecutor() ExecutorService Executors.newThreadPerTaskExecutor(ThreadFactory factory)
| Member | Description |
|---|---|
Thread.ofVirtual() |
Returns a builder for virtual threads. |
builder.name(String), name(String prefix, long start) |
Sets a fixed name, or a prefix with a counter. Virtual threads have no name by default. |
builder.start(Runnable) |
Creates and starts the thread. |
builder.unstarted(Runnable) |
Creates the thread without starting it. |
builder.factory() |
A ThreadFactory producing virtual threads. |
Thread.startVirtualThread(Runnable) |
Shortcut for an unnamed, started virtual thread. |
isVirtual() |
true for a virtual thread. |
Usage notes
- Do not pool them. Pooling exists to share a scarce resource; virtual threads are not scarce. Create one per task and let it end. Limit concurrency to a downstream resource with a
Semaphoreinstead. - They are always daemon threads, so they never keep the JVM alive, and their priority is fixed at
NORM_PRIORITY.setDaemon(false)throwsIllegalArgumentException. - Best for blocking I/O and waiting. Long CPU-bound loops get no benefit; the number of carrier threads equals the CPU count by default.
- Pinning. A virtual thread that blocks inside
synchronizedcould pin its carrier in Java 21 to 23. Since Java 24 (JEP 491) monitors no longer pin, but blocking inside native code or a foreign call still can. PreferReentrantLockin code that targets older releases. ThreadLocalworks but gives every virtual thread its own copy, which is expensive with millions of threads; keep thread-local values small or avoid them.- Thread dumps and debuggers treat them like normal threads, but
jcmd <pid> Thread.dump_to_file -format=jsonis needed to see all of them. - Structured concurrency (
StructuredTaskScope) is a separate API that was still a preview feature in Java 25; check the release notes before using it. - Same API. Interrupts,
join,ThreadLocalandThread.currentThread()behave as they do for platform threads.