Summary

Virtual threads were a preview feature in Java 19 (JEP 425) and Java 20 (JEP 436). JEP 444 proposes to make Virtual Threads a permanent feature.

There is one change to the API. The preview API to opt-out of thread locals, Thread.Builder.allowSetThreadLocals(boolean), has been dropped.

Problem

The goal is to enable server applications written in the simple thread-per-request style to scale. The Motivation section of the JEP provides a lot of discussion on this topic and how some developers workaround the limitation by giving up on the thread-per-request style in favor of thread-sharing and the asynchronous style.

Solution

The following APIs are proposed to be permanent APIs. The @since/equivalent changes to 21 as per guidance in JEP 12.

interface java.lang.Thread.Builder
interface java.lang.Thread.Builder.OfPlatform
interface java.lang.Thread.Builder.OfVirtual
method java.lang.Thread.ofPlatform()
method java.lang.Thread.ofVirtual()
method java.lang.Thread.startVirtualThread()
method java.lang.Thread.isVirtual()
method java.util.concurrent.Executors.newThreadPerTaskExecutor(ThreadFactory)
method java.util.concurrent.Executors.newVirtualThreadPerTaskExecutor()
method com.sun.jdi.ThreadReference.isVirtual()
method com.sun.jdi.request.ThreadStartRequest.addPlatformThreadsOnlyFilter()
method com.sun.jdi.request.ThreadDeathRequest.addPlatformThreadsOnlyFilter()
enum com.sun.management.HotSpotDiagnosticMXBean.ThreadDumpFormat
method com.sun.management.HotSpotDiagnosticMXBean.dumpThreads(String, ThreadDumpFormat)
method jdk.jfr.consumer.RecordedThread.isVirtual()
JNI function IsVirtualThread
JVMTI function SuspendAllVirtualThreads
JVMTI function ResumeAllVirtualThreads
JVMTI event VirtualThreadStart
JVMTI event VirtualThreadEnd
JVMTI capability can_support_virtual_threads
JDWP command ThreadReference/IsVirtual
JDWP modifier EventRequest/Set.PlatformThreadsOnly

The feature includes the following command line options:

jcmd Thread.dump_to_file [-format=json] [-overwrite] file
jdb -trackallthreads
JDWP agent sub option includevirtualthreads=y

The feature includes the following system properties:

jdk.virtualThreadScheduler.parallelism
jdk.virtualThreadScheduler.maxPoolSize
jdk.tracePinnedThreads
jdk.traceVirtualThreadLocals (new)

The feature includes the following file format:

Thread dump JSON format

The feature includes the following Java Flight Recorder events:

jdk.VirtualThreadStart
jdk.VirtualThreadEnd
jdk.VirualThreadPinned
jdk.VirtualThreadSubmitFailed

Specification

API changes - see attached zip file with specdiffs. Changes to highlight:

• Thread.ofVirtual, Thread.startVirtualThread, Executors.newVirtualThreadPerTaskExector, and StructuredTaskExecutor no longer throw UOE
• Thread.Builder.allowSetThreadLocals(boolean), and the overrides of this method in Thread.Builder.OfPlatform and Thread.Builder.OfVirtual, have been dropped
• ThreadLocal.set and Thread.setContextClassLoader no longer throws UOE
• Thread.Builder permits no longer include an implementation class. This is an implementation change but it has the effect of enabling switching over Thread.Builder subclasses exhaustively.

Java Native Interface (JNI) spec:

• Add JNI_VERSION_21 = 0x00150000
• Update GetVersion to return JNI_VERSION_21 on implementations of Java SE 21+
• Change IsVirtualtThread to be permanent and "since" to 21

Java Virtual Machine Tool Interface (JVM TI) spec:

• Add JVMTI_VERSION_21 = 0x30150000
• Change SuspendAllVirtualThreads and ResumeAllVirtualThreads functions to be permanent and "since" to 21
• Change VirtualThreadStart and VirtualThreadEnd events to be permanent and "since" to 21
• Change can_support_virtual_threads capability to be permanent and "since" to 21

Java Debug Wire Protocol spec:

• Change ThreadReference/IsVirtual command to be permanent and "since" to 21
• Change EventRequest Set/PlatformThreadsOnly modifier to be permanent and "since" to 21