< prev index next >

src/hotspot/share/prims/jvmti.xml

Print this page
@@ -132,10 +132,12 @@
  
     <!ELEMENT varargs EMPTY>
  
     <!ELEMENT jthreadGroup EMPTY>
     <!ELEMENT jobject EMPTY>
+    <!ATTLIST jobject frame CDATA #IMPLIED>
+ 
     <!ELEMENT jvalue EMPTY>
     <!ELEMENT jchar EMPTY>
     <!ELEMENT jint EMPTY>
     <!ATTLIST jint min CDATA #IMPLIED>
     <!ELEMENT jlong EMPTY>

@@ -1126,10 +1128,20 @@
      </function>
    </category>
  
    <category id="threadCategory" label="Thread">
      <intro>
+         These functions provide information about threads and allow an agent to
+         suspend and resume threads.
+         <p/>
+         The <code>jthread</code> specified to these functions can be a JNI
+         reference to a
+         <externallink id="../api/java.base/java/lang/Thread.html#platform-threads">platform thread</externallink>
+         or <externallink id="../api/java.base/java/lang/Thread.html#virtual-threads">virtual thread</externallink>.
+         Some functions are not supported on virtual threads and return
+         <code>JVMTI_ERROR_INVALID_THREAD</code> when called with a reference
+         to a virtual thread.
      </intro>
  
      <function id="GetThreadState" num="17">
        <synopsis>Get Thread State</synopsis>
        <description>

@@ -1220,13 +1232,13 @@
            </constant>
            <constant id="JVMTI_THREAD_STATE_RUNNABLE" num="0x0004">
              Thread is runnable.
            </constant>
            <constant id="JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER" num="0x0400">
-             Thread is waiting to enter a synchronization block/method or,
+             Thread is waiting to enter a synchronized block/method or,
              after an <code>Object.wait()</code>, waiting to re-enter a
-             synchronization block/method.
+             synchronized block/method.
            </constant>
            <constant id="JVMTI_THREAD_STATE_WAITING" num="0x0080">
              Thread is waiting.
            </constant>
            <constant id="JVMTI_THREAD_STATE_WAITING_INDEFINITELY" num="0x0010">

@@ -1236,18 +1248,20 @@
            <constant id="JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT" num="0x0020">
              Thread is waiting with a maximum time to wait specified.
              For example, <code>Object.wait(long)</code>.
            </constant>
            <constant id="JVMTI_THREAD_STATE_SLEEPING" num="0x0040">
-             Thread is sleeping -- <code>Thread.sleep(long)</code>.
+             Thread is sleeping -- <code>Thread.sleep</code>.
            </constant>
            <constant id="JVMTI_THREAD_STATE_IN_OBJECT_WAIT" num="0x0100">
              Thread is waiting on an object monitor -- <code>Object.wait</code>.
            </constant>
            <constant id="JVMTI_THREAD_STATE_PARKED" num="0x0200">
              Thread is parked, for example: <code>LockSupport.park</code>,
              <code>LockSupport.parkUtil</code> and <code>LockSupport.parkNanos</code>.
+             A virtual thread that is sleeping, in <code>Thread.sleep</code>, may
+             have this state flag set instead of <code>JVMTI_THREAD_STATE_SLEEPING</code>.
            </constant>
            <constant id="JVMTI_THREAD_STATE_SUSPENDED" num="0x100000">
              Thread suspended.
              <code>java.lang.Thread.suspend()</code>
              or a <jvmti/> suspend function

@@ -1511,36 +1525,35 @@
      </function>
  
      <function id="GetAllThreads" num="4">
        <synopsis>Get All Threads</synopsis>
        <description>
-         Get all live threads.
-         The threads are Java programming language threads;
-         that is, threads that are attached to the VM.
+         Get all live platform threads that are attached to the VM.
+         The list of threads includes
+         <internallink id="RunAgentThread">agent threads</internallink>.
+         It does not include virtual threads.
          A thread is live if <code>java.lang.Thread.isAlive()</code>
          would return <code>true</code>, that is, the thread has
          been started and has not yet died.
          The universe of threads is determined by the context of the <jvmti/>
          environment, which typically is all threads attached to the VM.
-         Note that this includes <jvmti/> agent threads
-         (see <functionlink id="RunAgentThread"/>).
        </description>
        <origin>jvmdi</origin>
        <capabilities>
        </capabilities>
        <parameters>
          <param id="threads_count_ptr">
            <outptr><jint/></outptr>
            <description>
-             On return, points to the number of running threads.
+             On return, points to the number of threads.
            </description>
          </param>
          <param id="threads_ptr">
            <allocbuf outcount="threads_count_ptr"><jthread/></allocbuf>
              <description>
                On return, points to an array of references, one
-               for each running thread.
+               for each thread.
              </description>
          </param>
        </parameters>
        <errors>
        </errors>

@@ -1559,11 +1572,11 @@
        <capabilities>
          <required id="can_suspend"></required>
        </capabilities>
        <parameters>
          <param id="thread">
-           <jthread null="current"/>
+           <jthread null="current" impl="noconvert"/>
              <description>
                The thread to suspend.
              </description>
          </param>
        </parameters>

@@ -1710,10 +1723,57 @@
        </parameters>
        <errors>
        </errors>
      </function>
  
+     <function id="SuspendAllVirtualThreads" num="118" since="16">
+       <synopsis>Suspend All Virtual Threads</synopsis>
+       <description>
+         <b> SuspendAllVirtualThreads is a preview API of the Java platform. </b>
+         <i>Preview features may be removed in a future release, or upgraded to
+         permanent features of the Java platform.</i>.
+         <p/>
+         Suspend all virtual threads except those already suspended.
+         Virtual threads may be resumed with
+         <functionlink id="ResumeAllVirtualThreads"></functionlink> or
+         <functionlink id="ResumeThreadList"></functionlink> or
+         <functionlink id="ResumeThread"></functionlink>.
+         Virtual threads that are currently suspended do not change state.
+       </description>
+       <origin>new</origin>
+       <capabilities>
+         <required id="can_suspend"></required>
+         <required id="can_support_virtual_threads"></required>
+       </capabilities>
+       <parameters>
+         <param id="except_count">
+           <jint min="0"/>
+           <description>
+             The number of threads in the list of threads not to be suspended.
+           </description>
+         </param>
+         <param id="except_list">
+             <inbuf incount="except_count">
+               <jthread/>
+               <nullok>not an error if <code>except_count == 0</code></nullok>
+             </inbuf>
+             <description>
+               The list of threads not to be suspended.
+             </description>
+         </param>
+       </parameters>
+       <errors>
+         <error id="JVMTI_ERROR_INVALID_THREAD">
+           A thread in <paramlink id="except_list"></paramlink> was invalid.
+         </error>
+         <error id="JVMTI_ERROR_NULL_POINTER">
+           Both <paramlink id="except_list"></paramlink> was <code>NULL</code>
+           and <paramlink id="except_count"></paramlink> was non-zero.
+         </error>
+       </errors>
+     </function>
+ 
      <function id="ResumeThread" num="6">
        <synopsis>Resume Thread</synopsis>
        <description>
          Resume a suspended thread.
          Any threads currently suspended through

@@ -1727,11 +1787,11 @@
        <capabilities>
          <required id="can_suspend"></required>
        </capabilities>
        <parameters>
          <param id="thread">
-           <jthread/>
+           <jthread impl="noconvert"/>
              <description>
                The thread to resume.
              </description>
          </param>
        </parameters>

@@ -1791,14 +1851,61 @@
        </parameters>
        <errors>
        </errors>
      </function>
  
+    <function id="ResumeAllVirtualThreads" num="119" since="16">
+       <synopsis>Resume All Virtual Threads</synopsis>
+       <description>
+         <b> SuspendAllVirtualThreads is a preview API of the Java platform. </b>
+         <i>Preview features may be removed in a future release, or upgraded to
+         permanent features of the Java platform.</i>.
+         <p/>
+         Resume all virtual threads except those already resumed.
+         Virtual threads may be suspended with
+         <functionlink id="SuspendAllVirtualThreads"></functionlink> or
+         <functionlink id="SuspendThreadList"></functionlink> or
+         <functionlink id="SuspendThread"></functionlink>.
+         Virtual threads that are currently resumed do not change state.
+       </description>
+       <origin>new</origin>
+       <capabilities>
+         <required id="can_suspend"></required>
+         <required id="can_support_virtual_threads"></required>
+       </capabilities>
+       <parameters>
+         <param id="except_count">
+           <jint min="0"/>
+           <description>
+             The number of threads in the list of threads not to be resumed.
+           </description>
+         </param>
+         <param id="except_list">
+             <inbuf incount="except_count">
+               <jthread/>
+               <nullok>not an error if <code>except_count == 0</code></nullok>
+             </inbuf>
+             <description>
+               The list of threads not to be resumed.
+             </description>
+         </param>
+       </parameters>
+       <errors>
+         <error id="JVMTI_ERROR_INVALID_THREAD">
+           A thread in <paramlink id="except_list"></paramlink> was invalid.
+         </error>
+         <error id="JVMTI_ERROR_NULL_POINTER">
+           Both <paramlink id="except_list"></paramlink> was <code>NULL</code>
+           and <paramlink id="except_count"></paramlink> was non-zero.
+         </error>
+       </errors>
+     </function>
+ 
      <function id="StopThread" num="7">
        <synopsis>Stop Thread</synopsis>
        <description>
-         Send the specified asynchronous exception to the specified thread.
+         Send the specified asynchronous exception to the specified platform thread.
          Normally, this function is used to kill the specified thread with an
          instance of the exception <code>ThreadDeath</code>, similar to
          <code>java.lang.Thread.stop</code>.
        </description>
        <origin>jvmdi</origin>

@@ -1808,20 +1915,25 @@
        <parameters>
          <param id="thread">
            <jthread/>
              <description>
                The thread to stop.
-             </description>
+               The <code>thread</code> may not be a virtual thread. Otherwise, the error code
+               <errorlink id="JVMTI_ERROR_INVALID_THREAD"></errorlink> will be returned.
+              </description>
          </param>
          <param id="exception">
            <jobject/>
              <description>
                The asynchronous exception object.
              </description>
          </param>
        </parameters>
        <errors>
+         <error id="JVMTI_ERROR_INVALID_THREAD">
+           <paramlink id="thread"/> is a virtual thread.
+         </error>
        </errors>
      </function>
  
      <function id="InterruptThread" num="8">
        <synopsis>Interrupt Thread</synopsis>

@@ -1857,17 +1969,19 @@
          </field>
          <field id="priority">
            <jint/>
            <description>
              The thread priority.  See the thread priority constants:
-             <datalink id="jvmtiThreadPriority"></datalink>.
+             <datalink id="jvmtiThreadPriority"></datalink>. The priority of a
+             virtual thread is always <code>JVMTI_THREAD_NORM_PRIORITY</code>.
            </description>
          </field>
          <field id="is_daemon">
            <jboolean/>
            <description>
-             Is this a daemon thread?
+             Is this a daemon thread? The daemon status of a virtual thread is
+             always <code>JNI_TRUE</code>.
            </description>
          </field>
          <field id="thread_group">
            <jthreadGroup/>
            <description>

@@ -1917,11 +2031,11 @@
        <capabilities>
          <required id="can_get_owned_monitor_info"></required>
        </capabilities>
        <parameters>
          <param id="thread">
-           <jthread null="current"/>
+           <jthread null="current" impl="noconvert"/>
              <description>
                The thread to query.
              </description>
          </param>
          <param id="owned_monitor_count_ptr">

@@ -1971,11 +2085,11 @@
        <capabilities>
          <required id="can_get_owned_monitor_stack_depth_info"></required>
        </capabilities>
        <parameters>
          <param id="thread">
-           <jthread null="current"/>
+           <jthread null="current" impl="noconvert"/>
              <description>
                The thread to query.
              </description>
          </param>
          <param id="monitor_info_count_ptr">

@@ -2007,11 +2121,11 @@
        <capabilities>
          <required id="can_get_current_contended_monitor"></required>
        </capabilities>
        <parameters>
          <param id="thread">
-           <jthread null="current"/>
+           <jthread null="current" impl="noconvert"/>
              <description>
                The thread to query.
              </description>
          </param>
          <param id="monitor_ptr">

@@ -2121,11 +2235,13 @@
        <parameters>
          <param id="thread">
            <jthread impl="noconvert" started="no"/>
              <description>
                The thread to run.
-             </description>
+               The <code>thread</code> may not be a virtual thread. Otherwise, the error code
+               <errorlink id="JVMTI_ERROR_INVALID_THREAD"></errorlink> will be returned.
+              </description>
          </param>
          <param id="proc">
            <ptrtype>
              <struct>jvmtiStartFunction</struct>
            </ptrtype>

@@ -2156,10 +2272,13 @@
              <paramlink id="priority"/> is less than
              <datalink id="JVMTI_THREAD_MIN_PRIORITY"/>
                or greater than
              <datalink id="JVMTI_THREAD_MAX_PRIORITY"/>
          </error>
+         <error id="JVMTI_ERROR_INVALID_THREAD">
+           <paramlink id="thread"/> is a virtual thread.
+         </error>
        </errors>
      </function>
  
      <function id="SetThreadLocalStorage" jkernel="yes" impl="notrace" phase="start" num="103">
        <synopsis>Set Thread Local Storage</synopsis>

@@ -2180,11 +2299,11 @@
        <origin>jvmpi</origin>
        <capabilities>
        </capabilities>
        <parameters>
          <param id="thread">
-           <jthread null="current"/>
+           <jthread null="current" impl="noconvert"/>
              <description>
                Store to this thread.
              </description>
          </param>
          <param id="data">

@@ -2287,11 +2406,12 @@
            </description>
          </field>
          <field id="is_daemon">
            <jboolean/>
            <description>
-             Is this a daemon thread group?
+             <code>JNI_FALSE</code>.
+             The concept of daemon thread group no longer exists.
            </description>
          </field>
        </typedef>
        <description>
          Get information about the thread group. The fields of the

@@ -2321,11 +2441,13 @@
      </function>
  
      <function id="GetThreadGroupChildren" num="15">
        <synopsis>Get Thread Group Children</synopsis>
        <description>
-         Get the live threads and active subgroups in this thread group.
+         Get the live platform threads and the child thread groups in this
+         thread group.  Virtual threads are not considered live threads in
+         a thread group and not returned by this function.
        </description>
        <origin>jvmdi</origin>
        <capabilities>
        </capabilities>
        <parameters>

@@ -2348,17 +2470,17 @@
              </description>
          </param>
          <param id="group_count_ptr">
            <outptr><jint/></outptr>
            <description>
-             On return, points to the number of active child thread groups
+             On return, points to the number of child thread groups
            </description>
          </param>
          <param id="groups_ptr">
            <allocbuf outcount="group_count_ptr"><jthreadGroup/></allocbuf>
              <description>
-               On return, points to an array of the active child thread groups.
+               On return, points to an array of the child thread groups.
              </description>
          </param>
        </parameters>
        <errors>
        </errors>

@@ -2482,11 +2604,11 @@
        <origin>jvmpi</origin>
        <capabilities>
        </capabilities>
        <parameters>
          <param id="thread">
-           <jthread null="current"/>
+           <jthread null="current" impl="noconvert"/>
              <description>
                Fetch the stack trace of this thread.
              </description>
          </param>
          <param id="start_depth">

@@ -2541,12 +2663,15 @@
  
  
      <function id="GetAllStackTraces" num="100">
        <synopsis>Get All Stack Traces</synopsis>
        <description>
-         Get information about the stacks of all live threads
-         (including <internallink id="RunAgentThread">agent threads</internallink>).
+         Get the stack traces of all live platform threads attached to the VM.
+         The list includes the stack traces of
+         <internallink id="RunAgentThread">agent threads</internallink>.
+         It does not include the stack traces of virtual threads.
+         <p/>
          If <paramlink id="max_frame_count"/> is less than the depth of a stack,
          the <paramlink id="max_frame_count"/> topmost frames are returned for that thread,
          otherwise the entire stack is returned.
          The topmost frames, those most recently invoked, are at the beginning of the returned buffer.
          <p/>

@@ -2766,11 +2891,11 @@
        <origin>jvmdi</origin>
        <capabilities>
        </capabilities>
        <parameters>
          <param id="thread">
-           <jthread null="current"/>
+           <jthread null="current" impl="noconvert"/>
              <description>
                The thread to query.
              </description>
          </param>
          <param id="count_ptr">

@@ -2841,10 +2966,12 @@
        <parameters>
          <param id="thread">
            <jthread/>
              <description>
                The thread whose current frame is to be popped.
+               The <code>thread</code> may not be a virtual thread. Otherwise, the error code
+               <errorlink id="JVMTI_ERROR_INVALID_THREAD"></errorlink> will be returned.
              </description>
          </param>
        </parameters>
        <errors>
          <error id="JVMTI_ERROR_OPAQUE_FRAME">

@@ -2855,10 +2982,13 @@
            Thread was not suspended and was not the current thread.
          </error>
          <error id="JVMTI_ERROR_NO_MORE_FRAMES">
            There are less than two stack frames on the call stack.
          </error>
+         <error id="JVMTI_ERROR_INVALID_THREAD">
+           <paramlink id="thread"/> is a virtual thread.
+         </error>
        </errors>
      </function>
  
      <function id="GetFrameLocation" num="19">
        <synopsis>Get Frame Location</synopsis>

@@ -2870,11 +3000,11 @@
        <origin>jvmdiClone</origin>
        <capabilities>
        </capabilities>
        <parameters>
          <param id="thread">
-           <jthread null="current" frame="frame"/>
+           <jthread null="current" frame="frame" impl="noconvert"/>
            <description>
              The thread of the frame to query.
            </description>
          </param>
          <param id="depth">

@@ -2919,11 +3049,11 @@
        <capabilities>
          <required id="can_generate_frame_pop_events"></required>
        </capabilities>
        <parameters>
          <param id="thread">
-           <jthread null="current" frame="depth"/>
+           <jthread null="current" frame="depth" impl="noconvert"/>
            <description>
              The thread of the frame for which the frame pop event will be generated.
            </description>
          </param>
          <param id="depth">

@@ -2955,10 +3085,12 @@
        (as defined by
        <vmspec chapter="3.6"/>)
        for the specified thread at
        the time the function is called.
        <p/>
+       The <code>thread</code> may not be a virtual thread. Otherwise, the error code
+       <errorlink id="JVMTI_ERROR_INVALID_THREAD"></errorlink> will be returned.
        The specified thread must be suspended or must be the current thread.
        The return occurs when execution of Java programming
        language code is resumed on this thread.
        Between calling one of these functions and resumption
        of thread execution, the state of the stack is undefined.

@@ -3022,10 +3154,13 @@
          </error>
          <error id="JVMTI_ERROR_TYPE_MISMATCH">
            The supplied <paramlink id="value"/> is not compatible with the
            result type of the called method.
          </error>
+         <error id="JVMTI_ERROR_INVALID_THREAD">
+           <paramlink id="thread"/> is a virtual thread.
+         </error>
          <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
            Thread was not suspended and was not the current thread.
          </error>
          <error id="JVMTI_ERROR_NO_MORE_FRAMES">
            There are no more frames on the call stack.

@@ -3070,10 +3205,13 @@
            The result type of the called method is not
            <code>int</code>, <code>short</code>,
            <code>char</code>, <code>byte</code>, or
            <code>boolean</code>.
          </error>
+         <error id="JVMTI_ERROR_INVALID_THREAD">
+           <paramlink id="thread"/> is a virtual thread.
+         </error>
          <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
            Thread was not suspended and was not the current thread.
          </error>
          <error id="JVMTI_ERROR_NO_MORE_FRAMES">
            There are no frames on the call stack.

@@ -3113,10 +3251,13 @@
            this functionality on this frame.
          </error>
          <error id="JVMTI_ERROR_TYPE_MISMATCH">
            The result type of the called method is not <code>long</code>.
          </error>
+         <error id="JVMTI_ERROR_INVALID_THREAD">
+           <paramlink id="thread"/> is a virtual thread.
+         </error>
          <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
            Thread was not suspended and was not the current thread.
          </error>
          <error id="JVMTI_ERROR_NO_MORE_FRAMES">
            There are no frames on the call stack.

@@ -3156,10 +3297,13 @@
            this functionality on this frame.
          </error>
          <error id="JVMTI_ERROR_TYPE_MISMATCH">
            The result type of the called method is not <code>float</code>.
          </error>
+         <error id="JVMTI_ERROR_INVALID_THREAD">
+           <paramlink id="thread"/> is a virtual thread.
+         </error>
          <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
            Thread was not suspended and was not the current thread.
          </error>
          <error id="JVMTI_ERROR_NO_MORE_FRAMES">
            There are no frames on the call stack.

@@ -3197,10 +3341,13 @@
            Or the implementation is unable to provide this functionality on this frame.
          </error>
          <error id="JVMTI_ERROR_TYPE_MISMATCH">
            The result type of the called method is not <code>double</code>.
          </error>
+         <error id="JVMTI_ERROR_INVALID_THREAD">
+           <paramlink id="thread"/> is a virtual thread.
+         </error>
          <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
            Thread was not suspended and was not the current thread.
          </error>
          <error id="JVMTI_ERROR_NO_MORE_FRAMES">
            There are no frames on the call stack.

@@ -3234,10 +3381,13 @@
            this functionality on this frame.
          </error>
          <error id="JVMTI_ERROR_TYPE_MISMATCH">
            The called method has a result type.
          </error>
+         <error id="JVMTI_ERROR_INVALID_THREAD">
+           <paramlink id="thread"/> is a virtual thread.
+         </error>
          <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
            Thread was not suspended and was not the current thread.
          </error>
          <error id="JVMTI_ERROR_NO_MORE_FRAMES">
            There are no frames on the call stack.

@@ -5694,11 +5844,11 @@
        <capabilities>
          <required id="can_access_local_variables"></required>
        </capabilities>
        <parameters>
          <param id="thread">
-           <jthread null="current" frame="frame"/>
+           <jthread null="current" frame="frame" impl="noconvert"/>
            <description>
              The thread of the frame containing the variable's value.
            </description>
          </param>
          <param id="depth">

@@ -5747,11 +5897,11 @@
        <capabilities>
          <required id="can_access_local_variables"></required>
        </capabilities>
        <parameters>
          <param id="thread">
-           <jthread null="current" frame="frame"/>
+           <jthread null="current" frame="frame" impl="noconvert"/>
            <description>
              The thread of the frame containing the variable's value.
            </description>
          </param>
          <param id="depth">

@@ -5785,11 +5935,11 @@
        <capabilities>
          <required id="can_access_local_variables"></required>
        </capabilities>
        <parameters>
          <param id="thread">
-           <jthread null="current" frame="frame"/>
+           <jthread null="current" frame="frame" impl="noconvert"/>
            <description>
              The thread of the frame containing the variable's value.
            </description>
          </param>
          <param id="depth">

@@ -5837,11 +5987,11 @@
        <capabilities>
          <required id="can_access_local_variables"></required>
        </capabilities>
        <parameters>
          <param id="thread">
-           <jthread null="current" frame="frame"/>
+           <jthread null="current" frame="frame" impl="noconvert"/>
            <description>
              The thread of the frame containing the variable's value.
            </description>
          </param>
          <param id="depth">

@@ -5886,11 +6036,11 @@
        <capabilities>
          <required id="can_access_local_variables"></required>
        </capabilities>
        <parameters>
          <param id="thread">
-           <jthread null="current" frame="frame"/>
+           <jthread null="current" frame="frame" impl="noconvert"/>
            <description>
              The thread of the frame containing the variable's value.
            </description>
          </param>
          <param id="depth">

@@ -5935,11 +6085,11 @@
        <capabilities>
          <required id="can_access_local_variables"></required>
        </capabilities>
        <parameters>
          <param id="thread">
-           <jthread null="current" frame="frame"/>
+           <jthread null="current" frame="frame" impl="noconvert"/>
            <description>
              The thread of the frame containing the variable's value.
            </description>
          </param>
          <param id="depth">

@@ -10425,10 +10575,25 @@
            If this capability is enabled then the heap sampling method
            <functionlink id="SetHeapSamplingInterval"></functionlink> can be
            called and <eventlink id="SampledObjectAlloc"></eventlink> events can be generated.
          </description>
        </capabilityfield>
+       <capabilityfield id="can_support_virtual_threads" since="14">
+         <description>
+           <b> can_support_virtual_threads is a preview API of the Java platform. </b>
+           <i>Preview features may be removed in a future release, or upgraded to
+           permanent features of the Java platform.</i>.
+           <p/>
+           Can support virtual threads.
+           If this capability is enabled then the following functions can be called:
+           <functionlink id="SuspendAllVirtualThreads"></functionlink>, 
+           <functionlink id="ResumeAllVirtualThreads"></functionlink>,
+           and the following events can be enabled:
+           <eventlink id="VirtualThreadStart"></eventlink>,
+           <eventlink id="VirtualThreadEnd"></eventlink>,
+         </description>
+       </capabilityfield>
      </capabilitiestypedef>
  
      <function id="GetPotentialCapabilities" jkernel="yes" phase="onload" num="140">
        <synopsis>Get Potential Capabilities</synopsis>
        <description>

@@ -10782,10 +10947,12 @@
              supply CPU time for threads other than the current
              thread or which have more accurate information for
              the current thread (see
              <functionlink id="GetCurrentThreadCpuTimerInfo"/> vs
              <functionlink id="GetThreadCpuTimerInfo"/>).
+             The current thread may not be a virtual thread. Otherwise, the error code
+             <errorlink id="JVMTI_ERROR_INVALID_THREAD"></errorlink> will be returned.
              On many platforms this call will be equivalent to:
  <example>
    GetThreadCpuTime(env, NULL, nanos_ptr)
  </example>
        </description>

@@ -10815,10 +10982,13 @@
              it may appear to be a negative number.
            </description>
          </param>
        </parameters>
        <errors>
+         <error id="JVMTI_ERROR_INVALID_THREAD">
+           Current thread is a virtual thread.
+         </error>
        </errors>
      </function>
  
      <function id="GetThreadCpuTimerInfo" num="136">
        <synopsis>Get Thread CPU Timer Information</synopsis>

@@ -10879,11 +11049,13 @@
        <parameters>
          <param id="thread">
            <jthread null="current"/>
              <description>
                The thread to query.
-             </description>
+               The <code>thread</code> may not be a virtual thread. Otherwise, the error code
+                <errorlink id="JVMTI_ERROR_INVALID_THREAD"></errorlink> will be returned.
+              </description>
          </param>
          <param id="nanos_ptr">
            <outptr><jlong/></outptr>
            <description>
              On return, points to the CPU time used by the specified thread

@@ -10892,10 +11064,13 @@
              it may appear to be a negative number.
            </description>
          </param>
        </parameters>
        <errors>
+         <error id="JVMTI_ERROR_INVALID_THREAD">
+           <paramlink id="thread"/> is a virtual thread.
+         </error>
        </errors>
      </function>
  
      <function id="GetTimerInfo" phase="any" callbacksafe="safe" num="138">
        <synopsis>Get Timer Information</synopsis>

@@ -12689,12 +12864,19 @@
    </event>
  
    <event label="Thread Start"
           id="ThreadStart" const="JVMTI_EVENT_THREAD_START" num="52" phase="start">
      <description>
-       Thread start events are generated by a new thread before its initial
-       method executes.
+       A thread start event is generated by a new thread before its initial
+       method executes. Thread start events are generated by platform threads.
+       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.
        <p/>
        A 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

@@ -12724,12 +12906,20 @@
    </event>
  
    <event label="Thread End"
           id="ThreadEnd" const="JVMTI_EVENT_THREAD_END" filtered="thread" num="53" phase="start">
      <description>
-       Thread end events are generated by a terminating thread
-       after its initial method has finished execution.
+       A thread end event is generated by a terminating thread after its
+       initial method has finished execution.
+       Thread end events are generated by platform threads.
+       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.
        <p/>
        A 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

@@ -12756,10 +12946,138 @@
            </description>
        </param>
      </parameters>
    </event>
  
+  <event label="Virtual Thread Start"
+          id="VirtualThreadStart" const="JVMTI_EVENT_VIRTUAL_THREAD_START" filtered="thread" num="87" phase="start" since="14">
+     <description>
+       <b> VirtualThreadStart is a preview API of the Java platform. </b>
+       <i>Preview features may be removed in a future release, or upgraded to
+       permanent features of the Java platform.</i>.
+       <p/>
+       Virtual thread started events are generated before its initial method executes.
+       <p/>
+       The event is sent on the <paramlink id="thread"></paramlink>.
+     </description>
+     <origin>new</origin>
+     <capabilities>
+       <required id="can_support_virtual_threads">Can support virtual threads</required>
+     </capabilities>
+     <parameters>
+       <param id="jni_env">
+         <outptr>
+           <struct>JNIEnv</struct>
+         </outptr>
+           <description>
+             The JNI environment of the event (current) thread.
+           </description>
+       </param>
+       <param id="virtual_thread">
+         <jthread/>
+           <description>
+             Virtual thread started for execution.
+           </description>
+       </param>
+     </parameters>
+   </event>
+ 
+   <event label="Virtual Thread End"
+          id="VirtualThreadEnd" const="JVMTI_EVENT_VIRTUAL_THREAD_END" filtered="thread" num="88" phase="start" since="14">
+     <description>
+       <b> VirtualThreadEnd is a preview API of the Java platform. </b>
+       <i>Preview features may be removed in a future release, or upgraded to
+       permanent features of the Java platform.</i>.
+       <p/>
+       Virtual thread end events are generated after its initial method has finished execution.
+       <p/>
+       The event is sent on the <paramlink id="thread"></paramlink>.
+     </description>
+     <origin>new</origin>
+     <capabilities>
+       <required id="can_support_virtual_threads">Can support virtual threads</required>
+     </capabilities>
+     <parameters>
+       <param id="jni_env">
+         <outptr>
+           <struct>JNIEnv</struct>
+         </outptr>
+           <description>
+             The JNI environment of the event (current) thread.
+           </description>
+       </param>
+       <param id="virtual_thread">
+         <jthread/>
+           <description>
+             Virtual thread being ended.
+           </description>
+       </param>
+     </parameters>
+   </event>
+ 
+   <elide>
+   <event label="Virtual Thread Mount"
+          id="VirtualThreadMount" const="JVMTI_EVENT_VIRTUAL_THREAD_MOUNT" filtered="thread" num="89" phase="start" since="14">
+     <description>
+       Virtual thread mount events are generated before its method continue to execute on the mounted thread.
+       <p/>
+       The event is sent on the <paramlink id="thread"></paramlink> the virtual thread is mounted to.
+     </description>
+     <origin>new</origin>
+     <capabilities>
+       <required id="can_support_virtual_threads">Can support virtual threads</required>
+     </capabilities>
+     <parameters>
+       <param id="jni_env">
+         <outptr>
+           <struct>JNIEnv</struct>
+         </outptr>
+           <description>
+             The JNI environment of the event (current) thread.
+           </description>
+       </param>
+       <param id="virtual_thread">
+         <jthread/>
+           <description>
+             Virtual thread that is mounted.
+           </description>
+       </param>
+     </parameters>
+   </event>
+   </elide>
+ 
+   <elide>
+   <event label="Virtual Thread Unmount"
+          id="VirtualThreadUnmount" const="JVMTI_EVENT_VIRTUAL_THREAD_UNMOUNT" filtered="thread" num="90" phase="start" since="14">
+     <description>
+       Virtual thread unmount events are generated when the virtual thread is about to be unmounted from the carrier thread.
+       <p/>
+       The event is sent on the <paramlink id="thread"></paramlink> the virtual thread is unmounted from.
+     </description>
+     <origin>new</origin>
+     <capabilities>
+       <required id="can_support_virtual_threads">Can support virtual threads</required>
+     </capabilities>
+     <parameters>
+       <param id="jni_env">
+         <outptr>
+           <struct>JNIEnv</struct>
+         </outptr>
+           <description>
+             The JNI environment of the event (current) thread.
+           </description>
+       </param>
+       <param id="virtual_thread">
+         <jthread/>
+           <description>
+             Virtual thread that is unmounted.
+           </description>
+       </param>
+     </parameters>
+   </event>
+   </elide>
+ 
    <event label="Class Load"
           id="ClassLoad" const="JVMTI_EVENT_CLASS_LOAD" filtered="thread" phase="start" num="55">
      <description>
        A class load event is generated
        <functionlink id="GetLoadedClasses">when a class or interface is created.</functionlink>.
< prev index next >