8289439: Clarify relationship between ThreadStart/ThreadEnd and can_s…

…upport_virtual_threads capability

Reviewed-by: dholmes, dcubed, sspitsyn, cjplummer

src/hotspot/share/prims/jvmti.xml

@@ -12892,15 +12892,21 @@ myInit() {
          id="ThreadStart" const="JVMTI_EVENT_THREAD_START" num="52" phase="start">
     <description>
       A thread start event is generated by a new thread before its initial
-      method executes. The capability
+      method executes.
+      <p/>
+      This event is generated by platform threads. It is also generated by
+      virtual threads when the capability
       <internallink id="jvmtiCapabilities.can_support_virtual_threads">
-      <code>can_support_virtual_threads</code></internallink> determines
-      if a new virtual thread generates a <code>ThreadStart</code> event or
-      a <eventlink id="VirtualThreadStart"/> event. If disabled, a virtual
-      thread generates a <code>ThreadStart</code> event. If enabled, a virtual
-      thread generates a <code>VirtualThreadStart</code> event.
+      <code>can_support_virtual_threads</code></internallink> is not enabled.
+      Agents without support for virtual threads that enable this event will
+      therefore be notified by all newly started threads.
+      <p/>
+      If the capability <code>can_support_virtual_threads</code> is enabled then
+      this event is not generated by virtual threads. Agents with support for
+      virtual threads can enable <eventlink id="VirtualThreadStart"></eventlink>
+      to be notified by newly started virtual threads.
       <p/>
-      A thread may be listed in the array returned by
+      A platform thread may be listed in the array returned by
       <functionlink id="GetAllThreads"></functionlink>
       before its thread start event is generated.
       It is possible for other events to be generated
@@ -12934,21 +12940,26 @@ myInit() {
     <description>
       A thread end event is generated by a terminating thread after its
       initial method has finished execution.
-      The capability
+      <p/>
+      This event is generated by platform threads. It is also generated by
+      virtual threads when the capability
       <internallink id="jvmtiCapabilities.can_support_virtual_threads">
-      <code>can_support_virtual_threads</code></internallink> determines
-      if a terminating virtual thread generates a <code>ThreadEnd</code>
-      event or a <eventlink id="VirtualThreadEnd"/> event. If disabled, a
-      virtual thread generates a <code>ThreadEnd</code> event. If enabled,
-      a virtual thread generates a <code>VirtualThreadEnd</code> event.
+      <code>can_support_virtual_threads</code></internallink> is not enabled.
+      Agents without support for virtual threads that enable this event for
+      all threads will therefore be notified by all terminating threads.
+      <p/>
+      If the capability <code>can_support_virtual_threads</code> is enabled then
+      this event is not generated by virtual threads. Agents with support for
+      virtual threads can enable <eventlink id="VirtualThreadEnd"></eventlink>
+      to be notified by terminating virtual threads.
       <p/>
-      A thread may be listed in the array returned by
+      A platform thread may be listed in the array returned by
       <functionlink id="GetAllThreads"></functionlink>
       after its thread end event is generated.
       No events are generated on a thread
       after its thread end event.
       <p/>
-      The event is sent on the dying <paramlink id="thread"></paramlink>.
+      The event is sent on the terminating <paramlink id="thread"></paramlink>.
     </description>
     <origin>jvmdi</origin>
     <capabilities>
@@ -12980,7 +12991,7 @@ myInit() {
       <p/>
       A virtual thread start event is generated before its initial method executes.
       <p/>
-      The event is sent on the <paramlink id="virtual_thread"></paramlink>.
+      The event is sent on the newly started <paramlink id="virtual_thread"></paramlink>.
     </description>
     <origin>new</origin>
     <capabilities>
@@ -13013,7 +13024,7 @@ myInit() {
       <p/>
       A virtual thread end event is generated after its initial method has finished execution.
       <p/>
-      The event is sent on the <paramlink id="virtual_thread"></paramlink>.
+      The event is sent on the terminating <paramlink id="virtual_thread"></paramlink>.
     </description>
     <origin>new</origin>
     <capabilities>

src/hotspot/share/prims/jvmtiH.xsl

@@ -115,6 +115,7 @@ enum {
     JVMTI_VERSION_1_2 = 0x30010200,
     JVMTI_VERSION_9   = 0x30090000,
     JVMTI_VERSION_11  = 0x300B0000,
+    JVMTI_VERSION_19  = 0x30130000,
 
     JVMTI_VERSION = 0x30000000 + (</xsl:text>
   <xsl:value-of select="$majorversion"/>