Virtual threads are just objects in the heap, there may be millions of them. There is no API support in the debugger API for enumerating all virtual threads.
JDI VirtualThreads.allThreads() (and JDWP VirtualMachine/AllThreads) enumerates all active live platform threads, virtual threads are not enumerated unless the JDWP agent is started with the includevirtualthreads option (see below).
For thread dumps and troubleshooting purposes the debugger can invoke the com.sun.management.ThreadsHotSpotDiagnosticMXBean.dumpThreads API in the target VM to enumerate threadsgenerate a thread dump. This can be used as stop-gap solution until there is better support in the debugging in the APIs for finding virtual threads in the debugger APIs.
Virtual threads are not active members of a thread group.
JDI ThreadStartEvent/ThreadDeathEvents are sent for all threads when enabled. This may impact performance if there are a huge number of virtual threads.
JDWP EventRequest/Set defines a new PlatformThreadsOnly filter that can be used when requesting THREAD_START and THREAD_END events. This allows these events to be filtered for virtual threads so they are not sent to the front-end/debugger.
JDI ThreadReference defines isVirtual() to test if a thread is a virtual thread.
JDWP ThreadReference/IsVirtual is the equivalent.
Testing if target VM supports virtual threads
The following recommend way is temporary, to allow debuggers to distinguish JDK 17 EA builds from Loom EA builds.JDI VirtualMachine defines supportVirtualThreads() to test to check if the target VM supports virtual threads.The supportsVirtualThread boolean in the reply to the JDWP CapabilitiesNew command is the equivalentis version 19 or later. There is no way to determine if --enable-preview was set, but this is also unnecessary. The JDK 19 debug agent will still execute commands that are virtual thread specific, even if the JVM was not run with --enable-preview.
The following are not currently supported for virtual threads:
- JDI ThreadReference.stop
- JDI ThreadReference.popFrame
- JDI ThreadReference.forceEarlyReturn
- JDI StackFrame.setValue() has limited support. It can be used on the topmost frame when suspended due to certain events, such as breakpoint and single step. Details are still being refined.
JDWP agent options
As a temporary solution to allow existing debuggers to work with virtual threads, the JDWP agent will track virtual threads so they can be enumerated for debuggers that want to enumerate all virtual threads. The options option that control controls this behavior areis:
|Option Name and Value||Description||Default|
|enumeratevthreadsincludevirtualthreads=y|n thread lists include vthreads||List of all threads includes virtual threads as well as platform threads||n|
- enumeratevthreads control includevirtualthreads control whether or not virtual threads are included in the list of threads returned by JDWP VirtualThread.GetAllThreads and ThreadGroupReference.Children commands. This flag can be turned on for compatibility purposes. This flag will may eventually go away and the debug agent will operate as if it was set to 'n'.
- [notifyvthreads has been removed. To disable THREAD_START and THREAD_END events for vthreads, use the PlatformThreadsOnly filter as described in this section] notifyvthreads controls whether or not THREAD_START and THREAD_END events are sent for vthreadsvirtual threads. The default is to send them. The purpose is to allow debugger writers to set to 'n' use notifyvthreads=n to see how the debugger works without getting these events. This is meant as a short term convenience flag rather than having to set the PlatformThreadsOnly filter as described above. In the long run Once support for notifyvthreads=n is gone, if debuggers don't want these eventswant THREAD_START and THREAD_END events for virtual threads, they will need to set the PlatformThreadsOnly filter. Since this means no When using the PlatformThreadsOnly filter, the debugger can learn about virtual threads when events are delivered for them, such as a BreakpointEvent. Since no THREAD_END event will be sent for the virtual thread, the debugger will then need to figure out how to "forget" about virtual Threads that the virtual threads it is tracking when they have terminated. This could possibly be done with an ObjectReference.IsCollected commanda ThreadDeathRequest that filters on the virtual thread. This would need to be done for each virtual thread being tracked by the debugger. Please note that notifyvthreads=y will not override any PlatformThreadsOnly filter that is in place.
Issues with too many virtual threads hitting breakpoints