Notes for debugger maintainers

Enumerating Threads

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

JDI VirtualThreads.allThreads (and JDWP VirtualMachine/AllThreads) continue to enumerate all platform threads.

Thread groups

Virtual threads are not active members of a thread group. 

JDI ThreadGroupReference::threads (and JDWP ThreadGroupReference/Children) continue to enumerate all platform threads in the group.

ThreadStart/ThreadEnd events

JDWP EventRequest/Set defines a new modifier VirtualThreadsExclude that can be used when request event kinds THREAD_START and THREAD_END to filer those events for virtual threads.

JDI ThreadStartRequest/ThreadDeathRequest define a new method removeVirtualThreadFilter that can be used to remove the filtering of thread start/end events for virtual threads. This may be changed so that JDI clients opt-out rather than opt-in for these events.

Not Supported

The following are current not supported for virtual threads:

• JDI ThreadReference::stop / JDWP ThreadReference/Stop
• JDI ThreadReference::interrupt / JDWP ThreadReference/Interrupt
• ForceEarlyReturn
• Set locals

JDWP agent options (temporary)

Option Name and Value           Description                       Default
---------------------           -----------                       -------

trackvthreads=some|all           track some or all vthreads       some
enumeratevthreads=y|n           thread lists include vthreads     y
fakevthreadstartevent=y|n       send fake start event when needed y

1. enumeratevthreads control whether or not vthreads are included in VM.allThreads and ThreadGroupReference.children.

2. trackvthreads determines what vthreads will be returned if enumeratevthreads=y, so it doesn’t carry any meaning to the user if enumeratevthreads=n, but will still impact with the debug agent does internally

3. 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 vthread the event occurred on. Intellij needs this. 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 vthreads have been created (a mode I haven’t even tested yet, and I don’t think is commonly used). (edited)