Skip to content
Tutorials Center
My learning

Topics

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.

Java
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

Java Ten thousand sleeping threads

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.

Java Creating and inspecting virtual threads

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

Java
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 Semaphore instead.
  • They are always daemon threads, so they never keep the JVM alive, and their priority is fixed at NORM_PRIORITY. setDaemon(false) throws IllegalArgumentException.
  • 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 synchronized could 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. Prefer ReentrantLock in code that targets older releases.
  • ThreadLocal works 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=json is 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, ThreadLocal and Thread.currentThread() behave as they do for platform threads.