Notes for debugger maintainers

Enumerating Threads

Virtual threads are just objects in the heap, there may be millions of them. There is no API support for enumerating all virtual threads.

JDI VirtualThreads.allThreads (and JDWP VirtualMachine/AllThreads) enumerates all active platform threads, as before.

Thread groups

Virtual threads are not active members of a thread group. 

JDI ThreadGroupReference::threads (and JDWP ThreadGroupReference/Children) enumerate all active platform threads in the group, as before.

ThreadStart/ThreadEnd events

ThreadStartEvent/ThreadDeathEvents can be sent for all virtual threads but it may impact performance.

JDWP EventRequest/Set defines a new modifier VirtualThreadsExclude 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 ThreadStartRequest/ThreadDeathRequest define a new method to control the filtering of thread start/end events for virtual threads (the current API requires JDI clients to opt-in to remove the filter, this will be changed so that JDI opt-out by adding a filter).

Not Supported

The following are not currently supported for virtual threads:

• JDI ThreadReference.stop
• JDI ThreadReference.interrupt
• JDI ThreadReference.popFrame
• JDI ThreadReference.forceEarlyReturn
• JDI StackFrame.setValue

JDWP agent options

As a temporary solution to allow existing debuggers 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 that control this behaviour are:

• enumeratevthreads control whether or not virtual threads are included in list of threads returned by JDWP VirtualThread/AllThreads and ThreadGroupReference/Children commands.
• trackvthreads controls which virtual threads will be returned when enumeratevthreads=y.
• fakevthreadstartevent is independent of the two others. If y, then before sending an event, send a fake THREAD_START event for if the debugger hasn’t already been notified about the virtual thread that the event occurs on. Note currently there is a bug, and if trackvthreads=all, no fake THREAD_START will ever be sent. This is only an issue if the debug agent is started after some virtual threads have been created.

Links

Java Debug Interface (JDI)

JDWP protocol details

JVM Tool Interface