Summary

Update the descriptions of the ThreadStart and ThreadEnd events in the JVM TI specification to make it clear how they work with virtual threads.

Problem

JEP 425 updated the descriptions of the ThreadStart and ThreadEnd events to specify if these events are sent by virtual threads when an agent enables (or does not enable) the capability can_support_virtual_threads. The wording needs to be improved so that it's clear to maintainers of JVM TI agents how these events work for existing agents, and agents that are upgraded to support virtual threads.

Solution

Update the descriptions of the ThreadStart and ThreadEnd events to make it clear that existing agents (that don't know anything about virtual threads) will be notified of these events by virtual threads.

Update the descriptions to make it clear that agents that support virtual threads will not be sent these events by virtual threads. Instead, agents that support virtual threads can enable the newer VirtualThreadStart and VirtualThreadEnd events if they want to be notified by starting or terminating virtual threads.

Specification

In ThreadStart, change

"The capability can_support_virtual_threads determines if a new virtual thread generates a ThreadStart event or a VirtualThreadStart event. If disabled, a virtual thread generates a ThreadStart event. If enabled, a virtual thread generates a VirtualThreadStart event."

to

"This event is generated by platform threads. It is also generated by virtual threads when the capability can_support_virtual_threads is not enabled. Agents without support for virtual threads that enable this event will therefore be notified by all newly started threads.

If the capability can_support_virtual_threads is enabled then this event is not generated by virtual threads. Agents with support for virtual threads can enable VirtualThreadStart to be notified by newly started virtual threads."

In ThreadEnd, change

"The capability can_support_virtual_threads determines if a terminating virtual thread generates a ThreadEnd event or a VirtualThreadEnd event. If disabled, a virtual thread generates a ThreadEnd event. If enabled, a virtual thread generates a VirtualThreadEndevent."

to

"This event is generated by platform threads. It is also generated by virtual threads when the capability can_support_virtual_threads is not enabled. Agents without support for virtual threads that enable this event for all threads will therefore be notified by all terminating threads.

If the capability can_support_virtual_threadsis enabled then this event is not generated by virtual threads. Agents with support for virtual threads can enable VirtualThreadEnd to be notified by terminating virtual threads."

A specdiff is attached.