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

Implementation of Virtual Threads (Preview)

    XMLWordPrintable

Details

    • CSR
    • Resolution: Approved
    • P3
    • 19
    • core-libs
    • None
    • source, binary, behavioral
    • medium
    • Hide
      The "Risks and Assumptions" section of the JEP lists the behavioral compatibility issues. It also lists the behavioral differences between platform and virtual threads that might be observed when using existing code (or tools) with newer code that takes advantage of virtual threads.

      We repeat the potential behavioral compatibility issues for existing code/deployments here:

      1. Code that makes assumptions on the internal locking in some classes in java.io. The implementation has a system property that can be used to make the locking work like older JDK releases. We don't plan to document the system property at this time.

      2. Legacy (and terminally deprecated) ThreadGroup has been degraded.

      Testing to date with several large applications using many 3rd party libraries has not encountered any issues. Developers using the Early Access builds have not reported any issues.


      In addition, there are a few source incompatible API changes:

      - Thread defines several new instance methods and static methods. If code in an existing source file extends Thread and declares a method that conflict with any of the new methods then the file will not compile without change.

      - Thread.Builder is added as a nested interface. If code in an existing source file imports a class name Builder, and references "Builder" as a simple name in a subclass of Thread, then the file will not compile without change.


      Finally, there is one source and binary incompatible API change:

      The method `long threadId()`is added to Thread as a final method. If code in an existing source file extends Thread and declares a no-arg method named `threadId` then it will not compile without change. If there is existing compiled code that extends Thread with a no-arg method named `threadId` that returns a long then IncompatibleClassChangeError will be thrown. Note that the name "threadId" was chosen to reduce the potential for conflict with methods in existing code. Thread has historically used the getXXX convention and a corpus search did not find any subclasses with a method of this name. It is important to the integrity of the platform that the thread identifier does not change during the lifetime of the Thread.
      Show
      The "Risks and Assumptions" section of the JEP lists the behavioral compatibility issues. It also lists the behavioral differences between platform and virtual threads that might be observed when using existing code (or tools) with newer code that takes advantage of virtual threads. We repeat the potential behavioral compatibility issues for existing code/deployments here: 1. Code that makes assumptions on the internal locking in some classes in java.io. The implementation has a system property that can be used to make the locking work like older JDK releases. We don't plan to document the system property at this time. 2. Legacy (and terminally deprecated) ThreadGroup has been degraded. Testing to date with several large applications using many 3rd party libraries has not encountered any issues. Developers using the Early Access builds have not reported any issues. In addition, there are a few source incompatible API changes: - Thread defines several new instance methods and static methods. If code in an existing source file extends Thread and declares a method that conflict with any of the new methods then the file will not compile without change. - Thread.Builder is added as a nested interface. If code in an existing source file imports a class name Builder, and references "Builder" as a simple name in a subclass of Thread, then the file will not compile without change. Finally, there is one source and binary incompatible API change: The method `long threadId()`is added to Thread as a final method. If code in an existing source file extends Thread and declares a no-arg method named `threadId` then it will not compile without change. If there is existing compiled code that extends Thread with a no-arg method named `threadId` that returns a long then IncompatibleClassChangeError will be thrown. Note that the name "threadId" was chosen to reduce the potential for conflict with methods in existing code. Thread has historically used the getXXX convention and a corpus search did not find any subclasses with a method of this name. It is important to the integrity of the platform that the thread identifier does not change during the lifetime of the Thread.
    • Java API, System or security property, add/remove/modify command line option, File or wire format
    • SE

    Description

      This is the CSR for JEP 425: Virtual Threads (Preview) (JDK-8277131).

      Summary

      Introduce virtual threads to the Java Platform. Virtual threads are lightweight threads that dramatically reduce the effort of writing, maintaining, and observing high-throughput concurrent applications.

      Problem

      The goal of the JEP is to enable server applications written in the simple thread-per-request style to scale. Unfortunately, the number of threads is limited because the JDK implements java.lang.Thread as a thin wrapper over operating system threads. 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

      Introduce a lightweight implementation of threads that are provided by the JDK rather than the OS. This allows developers to write clear code in the thread-per-request style. The JEP provides lengthy discussion of the proposed solution.

      Specification

      The specdiffs for the Java APIs, JNI spec, JVM TI spec, and JDWP spec are attached.

      The Java API changes proposed include both SE and JDK-specific APIs. A number of APIs are proposed as preview APIs, a number of APIs are proposed as permanent APIs, one method in j.l.Thread is deprecated, and several terminally deprecated in j.l.ThreadGroup are degraded. No APIs are removed.

      The Java APIs include new methods on j.u.concurrent.ForkJoinPool and j.u.concurrent.ForkJoinTask. Prof. Doug Lea is working on a PR and CSR proposing to add these methods in Java 19, in which case they will drop-off the list of API changes here.

      The other interface changes in the JEP are JDK-specific:

      • New system properties. The system properties for configuration/tuning are documented in an implNote in the Thread class description

        • jdk.virtualThreadScheduler.parallelism (for tuning)
        • jdk.virtualThreadScheduler.maxPoolSize (for tuning)
        • jdk.tracePinnedThreads (for diagnostics)

      • New jdb command line option, documented in usage printed by jdb -help

        • -trackvthreads track virtual threads as they are created

      • New JDWP agent option, documented in usage printed by -agentlib:jdwp=help

        • enumeratevthreads=y|n thread lists include all vthreads, defaults to n

      • New jcmd command, documented in usage printed by jcmd <pid> help Thread.dump_to_file

        • jcmd Thread.dump_to_file [-format=json] [-overwrite] file

      • New thread dump in JSON format, intended for tools to parse.

      • New JFR events:

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

      Attachments

        Issue Links

          csr of

          Enhancement - null JDK-8284161 Implementation of Virtual Threads (Preview)

          • P3 - Major loss of function.
          • Resolved
          relates to

          CSR - null JDK-8304920 Implementation of Virtual Threads

          • P3 - Major loss of function.
          • Closed

          CSR - null JDK-8296673 Implementation of Virtual Threads (Second Preview)

          • P4 - Minor loss of function, or other problem where easy workaround is present.
          • Closed

          Activity

            People

              alanb Alan Bateman
              alanb Alan Bateman
              Daniel Fuchs, Dmitry Bessonov, Mandy Chung, Paul Sandoz, Ron Pressler, Serguei Spitsyn, Stuart Marks
              Votes:
              0 Vote for this issue
              Watchers:
              9 Start watching this issue

              Dates

                Created:
                Updated:
                Resolved: