Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8304920

Implementation of Virtual Threads

    XMLWordPrintable

Details

    • CSR
    • Resolution: Approved
    • P3
    • 21
    • core-libs
    • None
    • minimal
    • Hide
      The CSRs for JEP 425 (JDK-8284169) and JEP 436 (JDK-8296673) detailed the compatibility issues.

      There are no new compatibility issues to list here, except that early adopters making use of the preview API Thead.Builder.allowSetThreadLocals(boolean) in Java 19/20 will need to change their code.
      Show
      The CSRs for JEP 425 ( JDK-8284169 ) and JEP 436 ( JDK-8296673 ) detailed the compatibility issues. There are no new compatibility issues to list here, except that early adopters making use of the preview API Thead.Builder.allowSetThreadLocals(boolean) in Java 19/20 will need to change their code.
    • Java API, System or security property, add/remove/modify command line option, File or wire format
    • SE

    Description

      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

      Attachments

        Issue Links

          Activity

            People

              alanb Alan Bateman
              alanb Alan Bateman
              Ron Pressler
              Votes:
              0 Vote for this issue
              Watchers:
              4 Start watching this issue

              Dates

                Created:
                Updated:
                Resolved: