< prev index next >

src/hotspot/share/prims/jvmti.xml

Print this page

  117 
  118    <!ELEMENT jclass EMPTY>
  119    <!ATTLIST jclass method CDATA #IMPLIED
  120                     field  CDATA #IMPLIED>
  121 
  122    <!ELEMENT jframeID EMPTY>
  123    <!ATTLIST jframeID thread CDATA #IMPLIED>
  124 
  125    <!ELEMENT jrawMonitorID EMPTY>
  126 
  127    <!ELEMENT jthread EMPTY>
  128    <!ATTLIST jthread started CDATA #IMPLIED
  129                      null CDATA #IMPLIED
  130                      frame CDATA #IMPLIED
  131                      impl CDATA #IMPLIED>
  132 
  133    <!ELEMENT varargs EMPTY>
  134 
  135    <!ELEMENT jthreadGroup EMPTY>
  136    <!ELEMENT jobject EMPTY>


  137    <!ELEMENT jvalue EMPTY>
  138    <!ELEMENT jchar EMPTY>
  139    <!ELEMENT jint EMPTY>
  140    <!ATTLIST jint min CDATA #IMPLIED>
  141    <!ELEMENT jlong EMPTY>
  142    <!ELEMENT jfloat EMPTY>
  143    <!ELEMENT jdouble EMPTY>
  144    <!ELEMENT jlocation EMPTY>
  145    <!ELEMENT jboolean EMPTY>
  146    <!ELEMENT char EMPTY>
  147    <!ELEMENT uchar EMPTY>
  148    <!ELEMENT size_t EMPTY>
  149    <!ELEMENT void EMPTY>
  150    <!ELEMENT enum (#PCDATA)*>
  151    <!ELEMENT struct (#PCDATA)*>
  152 
  153    <!ELEMENT nullok ANY>
  154 
  155    <!ELEMENT ptrtype     ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
  156                                    jthreadGroup|jobject|jvalue), nullok?)>

 1111       <parameters>
 1112         <param id="mem">
 1113           <outbuf>
 1114             <uchar/>
 1115             <nullok>the call is ignored</nullok>
 1116           </outbuf>
 1117           <description>
 1118             A pointer to the beginning of the allocated memory.
 1119             Please ignore "On return, the elements are set."
 1120               <todo>keep it from generating "On return, the elements are set"</todo>
 1121           </description>
 1122         </param>
 1123       </parameters>
 1124       <errors>
 1125       </errors>
 1126     </function>
 1127   </category>
 1128 
 1129   <category id="threadCategory" label="Thread">
 1130     <intro>










 1131     </intro>
 1132 
 1133     <function id="GetThreadState" num="17">
 1134       <synopsis>Get Thread State</synopsis>
 1135       <description>
 1136         Get the state of a thread.  The state of the thread is represented by the
 1137         answers to the hierarchical set of questions below:
 1138           <ul type="circle">
 1139             <li><i>Alive?</i>
 1140               <ul>
 1141                 <li>Not alive.
 1142                   <ul type="circle">
 1143                     <li><i>Why not alive?</i>
 1144                       <ul>
 1145                         <li>New.</li>
 1146                         <li>Terminated (<datalink
 1147                             id="JVMTI_THREAD_STATE_TERMINATED"><code>JVMTI_THREAD_STATE_TERMINATED</code></datalink>)</li>
 1148                       </ul>
 1149                     </li>
 1150                   </ul>

 1205                       </ul>
 1206                     </li>
 1207                   </ul>
 1208                 </li>
 1209               </ul>
 1210             </li>
 1211           </ul>
 1212         <p/>
 1213         The answers are represented by the following bit vector.
 1214         <constants id="jvmtiThreadState" label="Thread State Flags" kind="bits">
 1215           <constant id="JVMTI_THREAD_STATE_ALIVE" num="0x0001">
 1216             Thread is alive. Zero if thread is new (not started) or terminated.
 1217           </constant>
 1218           <constant id="JVMTI_THREAD_STATE_TERMINATED" num="0x0002">
 1219             Thread has completed execution.
 1220           </constant>
 1221           <constant id="JVMTI_THREAD_STATE_RUNNABLE" num="0x0004">
 1222             Thread is runnable.
 1223           </constant>
 1224           <constant id="JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER" num="0x0400">
 1225             Thread is waiting to enter a synchronization block/method or,
 1226             after an <code>Object.wait()</code>, waiting to re-enter a
 1227             synchronization block/method.
 1228           </constant>
 1229           <constant id="JVMTI_THREAD_STATE_WAITING" num="0x0080">
 1230             Thread is waiting.
 1231           </constant>
 1232           <constant id="JVMTI_THREAD_STATE_WAITING_INDEFINITELY" num="0x0010">
 1233             Thread is waiting without a timeout.
 1234             For example, <code>Object.wait()</code>.
 1235           </constant>
 1236           <constant id="JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT" num="0x0020">
 1237             Thread is waiting with a maximum time to wait specified.
 1238             For example, <code>Object.wait(long)</code>.
 1239           </constant>
 1240           <constant id="JVMTI_THREAD_STATE_SLEEPING" num="0x0040">
 1241             Thread is sleeping -- <code>Thread.sleep(long)</code>.
 1242           </constant>
 1243           <constant id="JVMTI_THREAD_STATE_IN_OBJECT_WAIT" num="0x0100">
 1244             Thread is waiting on an object monitor -- <code>Object.wait</code>.
 1245           </constant>
 1246           <constant id="JVMTI_THREAD_STATE_PARKED" num="0x0200">
 1247             Thread is parked, for example: <code>LockSupport.park</code>,
 1248             <code>LockSupport.parkUtil</code> and <code>LockSupport.parkNanos</code>.


 1249           </constant>
 1250           <constant id="JVMTI_THREAD_STATE_SUSPENDED" num="0x100000">
 1251             Thread suspended.
 1252             <code>java.lang.Thread.suspend()</code>
 1253             or a <jvmti/> suspend function
 1254             (such as <functionlink id="SuspendThread"></functionlink>)
 1255             has been called on the thread. If this bit
 1256             is set, the other bits refer to the thread state before suspension.
 1257           </constant>
 1258           <constant id="JVMTI_THREAD_STATE_INTERRUPTED" num="0x200000">
 1259             Thread has been interrupted.
 1260           </constant>
 1261           <constant id="JVMTI_THREAD_STATE_IN_NATIVE" num="0x400000">
 1262             Thread is in native code--that is, a native method is running
 1263             which has not called back into the VM or Java programming
 1264             language code.
 1265             <p/>
 1266             This flag is not set when running VM compiled Java programming
 1267             language code nor is it set when running VM code or
 1268             VM support code. Native VM interface functions, such as JNI and

 1496         the current thread.
 1497       </description>
 1498       <origin>new</origin>
 1499       <capabilities>
 1500       </capabilities>
 1501       <parameters>
 1502         <param id="thread_ptr">
 1503           <outptr><jthread/></outptr>
 1504           <description>
 1505              On return, points to the current thread, or <code>NULL</code>.
 1506           </description>
 1507         </param>
 1508       </parameters>
 1509       <errors>
 1510       </errors>
 1511     </function>
 1512 
 1513     <function id="GetAllThreads" num="4">
 1514       <synopsis>Get All Threads</synopsis>
 1515       <description>
 1516         Get all live threads.
 1517         The threads are Java programming language threads;
 1518         that is, threads that are attached to the VM.

 1519         A thread is live if <code>java.lang.Thread.isAlive()</code>
 1520         would return <code>true</code>, that is, the thread has
 1521         been started and has not yet died.
 1522         The universe of threads is determined by the context of the <jvmti/>
 1523         environment, which typically is all threads attached to the VM.
 1524         Note that this includes <jvmti/> agent threads
 1525         (see <functionlink id="RunAgentThread"/>).
 1526       </description>
 1527       <origin>jvmdi</origin>
 1528       <capabilities>
 1529       </capabilities>
 1530       <parameters>
 1531         <param id="threads_count_ptr">
 1532           <outptr><jint/></outptr>
 1533           <description>
 1534             On return, points to the number of running threads.
 1535           </description>
 1536         </param>
 1537         <param id="threads_ptr">
 1538           <allocbuf outcount="threads_count_ptr"><jthread/></allocbuf>
 1539             <description>
 1540               On return, points to an array of references, one
 1541               for each running thread.
 1542             </description>
 1543         </param>
 1544       </parameters>
 1545       <errors>
 1546       </errors>
 1547     </function>
 1548 
 1549     <function id="SuspendThread" num="5">
 1550       <synopsis>Suspend Thread</synopsis>
 1551       <description>
 1552         Suspend the specified thread. If the calling thread is specified,
 1553         this function will not return until some other thread calls
 1554         <functionlink id="ResumeThread"></functionlink>.
 1555         If the thread is currently suspended, this function
 1556         does nothing and returns an error.
 1557       </description>
 1558       <origin>jvmdi</origin>
 1559       <capabilities>
 1560         <required id="can_suspend"></required>
 1561       </capabilities>
 1562       <parameters>
 1563         <param id="thread">
 1564           <jthread null="current"/>
 1565             <description>
 1566               The thread to suspend.
 1567             </description>
 1568         </param>
 1569       </parameters>
 1570       <errors>
 1571         <error id="JVMTI_ERROR_THREAD_SUSPENDED">
 1572           Thread already suspended.
 1573         </error>
 1574       </errors>
 1575     </function>
 1576 
 1577     <elide>
 1578     <function id="SuspendAllThreads" num="101">
 1579       <synopsis>Suspend All Threads</synopsis>
 1580       <description>
 1581         <issue>
 1582             There has been no explicit call for this function, and it will
 1583             thus be removed if there is no interest.
 1584         </issue>

 1695         </param>
 1696         <param id="results">
 1697           <outbuf incount="request_count"><enum>jvmtiError</enum></outbuf>
 1698           <description>
 1699             An agent supplied array of
 1700             <paramlink id="request_count"></paramlink> elements.
 1701             On return, filled with the error code for
 1702             the suspend of the corresponding thread.
 1703             The error code will be
 1704             <errorlink id="JVMTI_ERROR_NONE"></errorlink>
 1705             if the thread was suspended by this call.
 1706             Possible error codes are those specified
 1707             for <functionlink id="SuspendThread"></functionlink>.
 1708           </description>
 1709         </param>
 1710       </parameters>
 1711       <errors>
 1712       </errors>
 1713     </function>
 1714 















































 1715     <function id="ResumeThread" num="6">
 1716       <synopsis>Resume Thread</synopsis>
 1717       <description>
 1718         Resume a suspended thread.
 1719         Any threads currently suspended through
 1720         a <jvmti/> suspend function (eg.
 1721         <functionlink id="SuspendThread"></functionlink>)
 1722         or <code>java.lang.Thread.suspend()</code>
 1723         will resume execution;
 1724         all other threads are unaffected.
 1725       </description>
 1726       <origin>jvmdi</origin>
 1727       <capabilities>
 1728         <required id="can_suspend"></required>
 1729       </capabilities>
 1730       <parameters>
 1731         <param id="thread">
 1732           <jthread/>
 1733             <description>
 1734               The thread to resume.
 1735             </description>
 1736         </param>
 1737       </parameters>
 1738       <errors>
 1739         <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
 1740           Thread was not suspended.
 1741         </error>
 1742         <error id="JVMTI_ERROR_INVALID_TYPESTATE">
 1743           The state of the thread has been modified, and is now inconsistent.
 1744         </error>
 1745       </errors>
 1746     </function>
 1747 
 1748     <function id="ResumeThreadList" num="93">
 1749       <synopsis>Resume Thread List</synopsis>
 1750       <description>
 1751         Resume the <paramlink id="request_count"></paramlink>
 1752         threads specified in the

 1776         </param>
 1777         <param id="results">
 1778           <outbuf incount="request_count"><enum>jvmtiError</enum></outbuf>
 1779           <description>
 1780             An agent supplied array of
 1781             <paramlink id="request_count"></paramlink> elements.
 1782             On return, filled with the error code for
 1783             the resume of the corresponding thread.
 1784             The error code will be
 1785             <errorlink id="JVMTI_ERROR_NONE"></errorlink>
 1786             if the thread was suspended by this call.
 1787             Possible error codes are those specified
 1788             for <functionlink id="ResumeThread"></functionlink>.
 1789           </description>
 1790         </param>
 1791       </parameters>
 1792       <errors>
 1793       </errors>
 1794     </function>
 1795 















































 1796     <function id="StopThread" num="7">
 1797       <synopsis>Stop Thread</synopsis>
 1798       <description>
 1799         Send the specified asynchronous exception to the specified thread.
 1800         Normally, this function is used to kill the specified thread with an
 1801         instance of the exception <code>ThreadDeath</code>, similar to
 1802         <code>java.lang.Thread.stop</code>.
 1803       </description>
 1804       <origin>jvmdi</origin>
 1805       <capabilities>
 1806         <required id="can_signal_thread"></required>
 1807       </capabilities>
 1808       <parameters>
 1809         <param id="thread">
 1810           <jthread/>
 1811             <description>
 1812               The thread to stop.
 1813             </description>


 1814         </param>
 1815         <param id="exception">
 1816           <jobject/>
 1817             <description>
 1818               The asynchronous exception object.
 1819             </description>
 1820         </param>
 1821       </parameters>
 1822       <errors>



 1823       </errors>
 1824     </function>
 1825 
 1826     <function id="InterruptThread" num="8">
 1827       <synopsis>Interrupt Thread</synopsis>
 1828       <description>
 1829         Interrupt the specified thread
 1830         (similar to <code>java.lang.Thread.interrupt</code>).
 1831       </description>
 1832       <origin>jvmdi</origin>
 1833       <capabilities>
 1834         <required id="can_signal_thread"></required>
 1835       </capabilities>
 1836       <parameters>
 1837         <param id="thread">
 1838           <jthread impl="noconvert"/>
 1839             <description>
 1840               The thread to interrupt.
 1841             </description>
 1842         </param>
 1843       </parameters>
 1844       <errors>
 1845       </errors>
 1846     </function>
 1847 
 1848     <function id="GetThreadInfo" num="9">
 1849       <synopsis>Get Thread Info</synopsis>
 1850       <typedef id="jvmtiThreadInfo" label="Thread information structure">
 1851         <field id="name">
 1852           <allocfieldbuf><char/></allocfieldbuf>
 1853           <description>
 1854             The thread name, encoded as a
 1855             <internallink id="mUTF">modified UTF-8</internallink> string.
 1856           </description>
 1857         </field>
 1858         <field id="priority">
 1859           <jint/>
 1860           <description>
 1861             The thread priority.  See the thread priority constants:
 1862             <datalink id="jvmtiThreadPriority"></datalink>.

 1863           </description>
 1864         </field>
 1865         <field id="is_daemon">
 1866           <jboolean/>
 1867           <description>
 1868             Is this a daemon thread?

 1869           </description>
 1870         </field>
 1871         <field id="thread_group">
 1872           <jthreadGroup/>
 1873           <description>
 1874             The thread group to which this thread belongs.
 1875             <code>NULL</code> if the thread has died.
 1876           </description>
 1877         </field>
 1878         <field id="context_class_loader">
 1879           <jobject/>
 1880             <description>
 1881               The context class loader associated with this thread.
 1882             </description>
 1883         </field>
 1884       </typedef>
 1885       <description>
 1886         Get thread information. The fields of the <datalink id="jvmtiThreadInfo"/> structure
 1887         are filled in with details of the specified thread.
 1888       </description>

 1902             On return, filled with information describing the specified thread.
 1903           </description>
 1904         </param>
 1905       </parameters>
 1906       <errors>
 1907       </errors>
 1908     </function>
 1909 
 1910     <function id="GetOwnedMonitorInfo" num="10">
 1911       <synopsis>Get Owned Monitor Info</synopsis>
 1912       <description>
 1913         Get information about the monitors owned by the
 1914         specified thread.
 1915       </description>
 1916       <origin>jvmdiClone</origin>
 1917       <capabilities>
 1918         <required id="can_get_owned_monitor_info"></required>
 1919       </capabilities>
 1920       <parameters>
 1921         <param id="thread">
 1922           <jthread null="current"/>
 1923             <description>
 1924               The thread to query.
 1925             </description>
 1926         </param>
 1927         <param id="owned_monitor_count_ptr">
 1928           <outptr><jint/></outptr>
 1929           <description>
 1930             The number of monitors returned.
 1931           </description>
 1932         </param>
 1933         <param id="owned_monitors_ptr">
 1934           <allocbuf outcount="owned_monitor_count_ptr"><jobject/></allocbuf>
 1935             <description>
 1936               The array of owned monitors.
 1937             </description>
 1938         </param>
 1939       </parameters>
 1940       <errors>
 1941       </errors>
 1942     </function>

 1956           <description>
 1957             The stack depth.  Corresponds to the stack depth used in the
 1958             <internallink id="stack">Stack Frame functions</internallink>.
 1959             That is, zero is the current frame, one is the frame which
 1960             called the current frame. And it is negative one if the
 1961             implementation cannot determine the stack depth (e.g., for
 1962             monitors acquired by JNI <code>MonitorEnter</code>).
 1963           </description>
 1964         </field>
 1965       </typedef>
 1966       <description>
 1967         Get information about the monitors owned by the
 1968         specified thread and the depth of the stack frame which locked them.
 1969       </description>
 1970       <origin>new</origin>
 1971       <capabilities>
 1972         <required id="can_get_owned_monitor_stack_depth_info"></required>
 1973       </capabilities>
 1974       <parameters>
 1975         <param id="thread">
 1976           <jthread null="current"/>
 1977             <description>
 1978               The thread to query.
 1979             </description>
 1980         </param>
 1981         <param id="monitor_info_count_ptr">
 1982           <outptr><jint/></outptr>
 1983           <description>
 1984             The number of monitors returned.
 1985           </description>
 1986         </param>
 1987         <param id="monitor_info_ptr">
 1988           <allocbuf outcount="monitor_info_count_ptr">
 1989             <struct>jvmtiMonitorStackDepthInfo</struct>
 1990           </allocbuf>
 1991           <description>
 1992             The array of owned monitor depth information.
 1993           </description>
 1994         </param>
 1995       </parameters>
 1996       <errors>
 1997       </errors>
 1998     </function>
 1999 
 2000     <function id="GetCurrentContendedMonitor" num="11">
 2001       <synopsis>Get Current Contended Monitor</synopsis>
 2002       <description>
 2003         Get the object, if any, whose monitor the specified thread is waiting to
 2004         enter or waiting to regain through <code>java.lang.Object.wait</code>.
 2005       </description>
 2006       <origin>jvmdi</origin>
 2007       <capabilities>
 2008         <required id="can_get_current_contended_monitor"></required>
 2009       </capabilities>
 2010       <parameters>
 2011         <param id="thread">
 2012           <jthread null="current"/>
 2013             <description>
 2014               The thread to query.
 2015             </description>
 2016         </param>
 2017         <param id="monitor_ptr">
 2018           <outptr><jobject/></outptr>
 2019             <description>
 2020               On return, filled with the current contended monitor, or
 2021               NULL if there is none.
 2022             </description>
 2023         </param>
 2024       </parameters>
 2025       <errors>
 2026       </errors>
 2027     </function>
 2028 
 2029     <callback id="jvmtiStartFunction">
 2030       <void/>
 2031       <synopsis>Agent Start Function</synopsis>
 2032       <description>

 2106         group at either the Java programming language or <jvmti/> levels.
 2107         <p/>
 2108         The thread is not visible to Java programming language queries but is
 2109         included in <jvmti/> queries (for example,
 2110         <functionlink id="GetAllThreads"/> and
 2111         <functionlink id="GetAllStackTraces"/>).
 2112         <p/>
 2113         Upon execution of <code>proc</code>, the new thread will be attached to the
 2114         VM -- see the JNI documentation on
 2115         <externallink id="jni/invocation.html#attaching-to-the-vm"
 2116                       >Attaching to the VM</externallink>.
 2117       </description>
 2118       <origin>jvmdiClone</origin>
 2119       <capabilities>
 2120       </capabilities>
 2121       <parameters>
 2122         <param id="thread">
 2123           <jthread impl="noconvert" started="no"/>
 2124             <description>
 2125               The thread to run.
 2126             </description>


 2127         </param>
 2128         <param id="proc">
 2129           <ptrtype>
 2130             <struct>jvmtiStartFunction</struct>
 2131           </ptrtype>
 2132           <description>
 2133             The start function.
 2134           </description>
 2135         </param>
 2136         <param id="arg">
 2137           <inbuf>
 2138             <void/>
 2139             <nullok><code>NULL</code> is passed to the start function</nullok>
 2140           </inbuf>
 2141           <description>
 2142             The argument to the start function.
 2143           </description>
 2144         </param>
 2145         <param id="priority">
 2146           <jint/>
 2147           <description>
 2148             The priority of the started thread. Any thread
 2149             priority allowed by <code>java.lang.Thread.setPriority</code> can be used including
 2150             those in <datalink id="jvmtiThreadPriority"></datalink>.
 2151           </description>
 2152         </param>
 2153       </parameters>
 2154       <errors>
 2155         <error id="JVMTI_ERROR_INVALID_PRIORITY">
 2156             <paramlink id="priority"/> is less than
 2157             <datalink id="JVMTI_THREAD_MIN_PRIORITY"/>
 2158               or greater than
 2159             <datalink id="JVMTI_THREAD_MAX_PRIORITY"/>
 2160         </error>



 2161       </errors>
 2162     </function>
 2163 
 2164     <function id="SetThreadLocalStorage" jkernel="yes" impl="notrace" phase="start" num="103">
 2165       <synopsis>Set Thread Local Storage</synopsis>
 2166       <description>
 2167         The VM stores a pointer value associated with each environment-thread
 2168         pair. This pointer value is called <i>thread-local storage</i>.
 2169         This value is <code>NULL</code> unless set with this function.
 2170         Agents can allocate memory in which they store thread specific
 2171         information. By setting thread-local storage it can then be
 2172         accessed with
 2173         <functionlink id="GetThreadLocalStorage"></functionlink>.
 2174         <p/>
 2175         This function is called by the agent to set the value of the <jvmti/>
 2176         thread-local storage. <jvmti/> supplies to the agent a pointer-size
 2177         thread-local storage that can be used to record per-thread
 2178         information.
 2179       </description>
 2180       <origin>jvmpi</origin>
 2181       <capabilities>
 2182       </capabilities>
 2183       <parameters>
 2184         <param id="thread">
 2185           <jthread null="current"/>
 2186             <description>
 2187               Store to this thread.
 2188             </description>
 2189         </param>
 2190         <param id="data">
 2191           <inbuf>
 2192             <void/>
 2193             <nullok>value is set to <code>NULL</code></nullok>
 2194           </inbuf>
 2195           <description>
 2196             The value to be entered into the thread-local storage.
 2197           </description>
 2198         </param>
 2199       </parameters>
 2200       <errors>
 2201       </errors>
 2202     </function>
 2203 
 2204     <function id="GetThreadLocalStorage" jkernel="yes" impl="innative notrace" phase="start" num="102">
 2205       <synopsis>Get Thread Local Storage</synopsis>

 2272           <description>
 2273             The parent thread group.
 2274           </description>
 2275         </field>
 2276         <field id="name">
 2277           <allocfieldbuf><char/></allocfieldbuf>
 2278           <description>
 2279             The thread group's name, encoded as a
 2280             <internallink id="mUTF">modified UTF-8</internallink> string.
 2281           </description>
 2282         </field>
 2283         <field id="max_priority">
 2284           <jint/>
 2285           <description>
 2286             The maximum priority for this thread group.
 2287           </description>
 2288         </field>
 2289         <field id="is_daemon">
 2290           <jboolean/>
 2291           <description>
 2292             Is this a daemon thread group?

 2293           </description>
 2294         </field>
 2295       </typedef>
 2296       <description>
 2297         Get information about the thread group. The fields of the
 2298         <functionlink id="jvmtiThreadGroupInfo"></functionlink> structure
 2299         are filled in with details of the specified thread group.
 2300       </description>
 2301       <origin>jvmdi</origin>
 2302       <capabilities>
 2303       </capabilities>
 2304       <parameters>
 2305         <param id="group">
 2306           <jthreadGroup/>
 2307           <description>
 2308             The thread group to query.
 2309           </description>
 2310         </param>
 2311         <param id="info_ptr">
 2312           <outptr><struct>jvmtiThreadGroupInfo</struct></outptr>
 2313           <description>
 2314             On return, filled with information describing the specified
 2315             thread group.
 2316           </description>
 2317         </param>
 2318       </parameters>
 2319       <errors>
 2320       </errors>
 2321     </function>
 2322 
 2323     <function id="GetThreadGroupChildren" num="15">
 2324       <synopsis>Get Thread Group Children</synopsis>
 2325       <description>
 2326         Get the live threads and active subgroups in this thread group.


 2327       </description>
 2328       <origin>jvmdi</origin>
 2329       <capabilities>
 2330       </capabilities>
 2331       <parameters>
 2332         <param id="group">
 2333           <jthreadGroup/>
 2334           <description>
 2335             The group to query.
 2336           </description>
 2337         </param>
 2338         <param id="thread_count_ptr">
 2339           <outptr><jint/></outptr>
 2340           <description>
 2341             On return, points to the number of live threads in this thread group.
 2342           </description>
 2343         </param>
 2344         <param id="threads_ptr">
 2345           <allocbuf outcount="thread_count_ptr"><jthread/></allocbuf>
 2346             <description>
 2347               On return, points to an array of the live threads in this thread group.
 2348             </description>
 2349         </param>
 2350         <param id="group_count_ptr">
 2351           <outptr><jint/></outptr>
 2352           <description>
 2353             On return, points to the number of active child thread groups
 2354           </description>
 2355         </param>
 2356         <param id="groups_ptr">
 2357           <allocbuf outcount="group_count_ptr"><jthreadGroup/></allocbuf>
 2358             <description>
 2359               On return, points to an array of the active child thread groups.
 2360             </description>
 2361         </param>
 2362       </parameters>
 2363       <errors>
 2364       </errors>
 2365     </function>
 2366   </category>
 2367 
 2368   <category id="stack" label="Stack Frame">
 2369     <intro>
 2370         These functions provide information about the stack of a thread.
 2371         Stack frames are referenced by depth.
 2372         The frame at depth zero is the current frame.
 2373         <p/>
 2374         Stack frames are as described in
 2375         <vmspec chapter="3.6"/>,
 2376         That is, they correspond to method
 2377         invocations (including native methods) but do not correspond to platform native or
 2378         VM internal frames.
 2379         <p/>

 2467       printf("Executing method: %s", methodName);
 2468    }
 2469 }
 2470         </example>
 2471         <todo>
 2472           check example code.
 2473         </todo>
 2474         <p/>
 2475         The <paramlink id="thread"></paramlink> need not be suspended
 2476         to call this function.
 2477         <p/>
 2478         The <functionlink id="GetLineNumberTable"></functionlink>
 2479         function can be used to map locations to line numbers. Note that
 2480         this mapping can be done lazily.
 2481       </description>
 2482       <origin>jvmpi</origin>
 2483       <capabilities>
 2484       </capabilities>
 2485       <parameters>
 2486         <param id="thread">
 2487           <jthread null="current"/>
 2488             <description>
 2489               Fetch the stack trace of this thread.
 2490             </description>
 2491         </param>
 2492         <param id="start_depth">
 2493           <jint/>
 2494           <description>
 2495             Begin retrieving frames at this depth.
 2496             If non-negative, count from the current frame,
 2497             the first frame retrieved is at depth <code>start_depth</code>.
 2498             For example, if zero, start from the current frame; if one, start from the
 2499             caller of the current frame; if two, start from the caller of the
 2500             caller of the current frame; and so on.
 2501             If negative, count from below the oldest frame,
 2502             the first frame retrieved is at depth <i>stackDepth</i><code> + start_depth</code>,
 2503             where <i>stackDepth</i> is the count of frames on the stack.
 2504             For example, if negative one, only the oldest frame is retrieved;
 2505             if negative two, start from the frame called by the oldest frame.
 2506           </description>
 2507         </param>

 2526             On return, points to the number of records filled in.
 2527             For non-negative <code>start_depth</code>, this will be
 2528             min(<code>max_frame_count</code>, <i>stackDepth</i><code> - start_depth</code>).
 2529             For negative <code>start_depth</code>, this will be
 2530             min(<code>max_frame_count</code>, <code>-start_depth</code>).
 2531           </description>
 2532         </param>
 2533       </parameters>
 2534       <errors>
 2535         <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
 2536           <paramlink id="start_depth"/> is positive and greater than or equal to <i>stackDepth</i>.
 2537           Or <paramlink id="start_depth"/> is negative and less than <i>-stackDepth</i>.
 2538         </error>
 2539       </errors>
 2540     </function>
 2541 
 2542 
 2543     <function id="GetAllStackTraces" num="100">
 2544       <synopsis>Get All Stack Traces</synopsis>
 2545       <description>
 2546         Get information about the stacks of all live threads
 2547         (including <internallink id="RunAgentThread">agent threads</internallink>).



 2548         If <paramlink id="max_frame_count"/> is less than the depth of a stack,
 2549         the <paramlink id="max_frame_count"/> topmost frames are returned for that thread,
 2550         otherwise the entire stack is returned.
 2551         The topmost frames, those most recently invoked, are at the beginning of the returned buffer.
 2552         <p/>
 2553         All stacks are collected simultaneously, that is, no changes will occur to the
 2554         thread state or stacks between the sampling of one thread and the next.
 2555         The threads need not be suspended.
 2556 
 2557         <example>
 2558 jvmtiStackInfo *stack_info;
 2559 jint thread_count;
 2560 int ti;
 2561 jvmtiError err;
 2562 
 2563 err = (*jvmti)-&gt;GetAllStackTraces(jvmti, MAX_FRAMES, &amp;stack_info, &amp;thread_count);
 2564 if (err != JVMTI_ERROR_NONE) {
 2565    ...
 2566 }
 2567 for (ti = 0; ti &lt; thread_count; ++ti) {

 2751           The thread being used to call this function is not attached
 2752           to the virtual machine.  Calls must be made from attached threads.
 2753         </error>
 2754       </errors>
 2755     </function>
 2756     </elide>
 2757 
 2758     <function id="GetFrameCount" num="16">
 2759       <synopsis>Get Frame Count</synopsis>
 2760       <description>
 2761         Get the number of frames currently in the specified thread's call stack.
 2762         <p/>
 2763         If this function is called for a thread actively executing bytecodes (for example,
 2764         not the current thread and not suspended), the information returned is transient.
 2765       </description>
 2766       <origin>jvmdi</origin>
 2767       <capabilities>
 2768       </capabilities>
 2769       <parameters>
 2770         <param id="thread">
 2771           <jthread null="current"/>
 2772             <description>
 2773               The thread to query.
 2774             </description>
 2775         </param>
 2776         <param id="count_ptr">
 2777           <outptr><jint/></outptr>
 2778           <description>
 2779             On return, points to the number of frames in the call stack.
 2780           </description>
 2781         </param>
 2782       </parameters>
 2783       <errors>
 2784       </errors>
 2785     </function>
 2786 
 2787     <function id="PopFrame" num="80">
 2788       <synopsis>Pop Frame</synopsis>
 2789       <description>
 2790         Pop the current frame of <code>thread</code>'s stack.
 2791         Popping a frame takes you to the previous frame.

 2826         Finally blocks are not executed.
 2827         <p/>
 2828         Changes to global state are not addressed and thus remain changed.
 2829         <p/>
 2830         The specified thread must be suspended or must be the current thread.
 2831         <p/>
 2832         Both the called method and calling method must be non-native Java programming
 2833         language methods.
 2834         <p/>
 2835         No <jvmti/> events are generated by this function.
 2836       </description>
 2837       <origin>jvmdi</origin>
 2838       <capabilities>
 2839         <required id="can_pop_frame"></required>
 2840       </capabilities>
 2841       <parameters>
 2842         <param id="thread">
 2843           <jthread/>
 2844             <description>
 2845               The thread whose current frame is to be popped.


 2846             </description>
 2847         </param>
 2848       </parameters>
 2849       <errors>
 2850         <error id="JVMTI_ERROR_OPAQUE_FRAME">
 2851           Called or calling method is a native method.
 2852           The implementation is unable to pop this frame.
 2853         </error>
 2854         <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
 2855           Thread was not suspended and was not the current thread.
 2856         </error>
 2857         <error id="JVMTI_ERROR_NO_MORE_FRAMES">
 2858           There are less than two stack frames on the call stack.
 2859         </error>



 2860       </errors>
 2861     </function>
 2862 
 2863     <function id="GetFrameLocation" num="19">
 2864       <synopsis>Get Frame Location</synopsis>
 2865       <description>
 2866         <p/>
 2867         For a Java programming language frame, return the location of the instruction
 2868         currently executing.
 2869       </description>
 2870       <origin>jvmdiClone</origin>
 2871       <capabilities>
 2872       </capabilities>
 2873       <parameters>
 2874         <param id="thread">
 2875           <jthread null="current" frame="frame"/>
 2876           <description>
 2877             The thread of the frame to query.
 2878           </description>
 2879         </param>
 2880         <param id="depth">
 2881           <jframeID thread="thread"/>
 2882           <description>
 2883             The depth of the frame to query.
 2884           </description>
 2885         </param>
 2886         <param id="method_ptr">
 2887           <outptr><jmethodID/></outptr>
 2888             <description>
 2889               On return, points to the method for the current location.
 2890             </description>
 2891         </param>
 2892         <param id="location_ptr">
 2893           <outptr><jlocation/></outptr>
 2894           <description>
 2895             On return, points to the index of the currently

 2904     </function>
 2905 
 2906     <function id="NotifyFramePop" num="20">
 2907       <synopsis>Notify Frame Pop</synopsis>
 2908       <description>
 2909         When the frame that is currently at <paramlink id="depth"></paramlink>
 2910         is popped from the stack, generate a
 2911         <eventlink id="FramePop"></eventlink> event.  See the
 2912         <eventlink id="FramePop"></eventlink> event for details.
 2913         Only frames corresponding to non-native Java programming language
 2914         methods can receive notification.
 2915         <p/>
 2916         The specified thread must be suspended or must be the current thread.
 2917       </description>
 2918       <origin>jvmdi</origin>
 2919       <capabilities>
 2920         <required id="can_generate_frame_pop_events"></required>
 2921       </capabilities>
 2922       <parameters>
 2923         <param id="thread">
 2924           <jthread null="current" frame="depth"/>
 2925           <description>
 2926             The thread of the frame for which the frame pop event will be generated.
 2927           </description>
 2928         </param>
 2929         <param id="depth">
 2930           <jframeID thread="thread"/>
 2931           <description>
 2932             The depth of the frame for which the frame pop event will be generated.
 2933           </description>
 2934         </param>
 2935       </parameters>
 2936       <errors>
 2937         <error id="JVMTI_ERROR_OPAQUE_FRAME">
 2938           The frame at <code>depth</code> is executing a
 2939           native method.
 2940         </error>
 2941         <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
 2942           Thread was not suspended and was not the current thread.
 2943         </error>
 2944       </errors>
 2945     </function>
 2946 
 2947   </category>
 2948 
 2949   <category id="ForceEarlyReturn" label="Force Early Return">
 2950     <intro>
 2951       These functions allow an agent to force a method
 2952       to return at any point during its execution.
 2953       The method which will return early is referred to as the <i>called method</i>.
 2954       The called method is the current method
 2955       (as defined by
 2956       <vmspec chapter="3.6"/>)
 2957       for the specified thread at
 2958       the time the function is called.
 2959       <p/>


 2960       The specified thread must be suspended or must be the current thread.
 2961       The return occurs when execution of Java programming
 2962       language code is resumed on this thread.
 2963       Between calling one of these functions and resumption
 2964       of thread execution, the state of the stack is undefined.
 2965       <p/>
 2966       No further instructions are executed in the called method.
 2967       Specifically, finally blocks are not executed.
 2968       Note: this can cause inconsistent states in the application.
 2969       <p/>
 2970       A lock acquired by calling the called method
 2971       (if it is a <code>synchronized</code>  method)
 2972       and locks acquired by entering <code>synchronized</code>
 2973       blocks within the called method are released.
 2974       Note: this does not apply to native locks or
 2975       <code>java.util.concurrent.locks</code> locks.
 2976       <p/>
 2977       Events, such as <eventlink id="MethodExit"></eventlink>,
 2978       are generated as they would be in a normal return.
 2979       <p/>

 3007             The return value for the called frame.
 3008             An object or <code>NULL</code>.
 3009           </description>
 3010         </param>
 3011       </parameters>
 3012       <errors>
 3013         <error id="JVMTI_ERROR_OPAQUE_FRAME">
 3014           Attempted to return early from a frame
 3015           corresponding to a native method.
 3016           Or the implementation is unable to provide
 3017           this functionality on this frame.
 3018         </error>
 3019         <error id="JVMTI_ERROR_TYPE_MISMATCH">
 3020           The result type of the called method is not
 3021           <code>Object</code> or a subclass of <code>Object</code>.
 3022         </error>
 3023         <error id="JVMTI_ERROR_TYPE_MISMATCH">
 3024           The supplied <paramlink id="value"/> is not compatible with the
 3025           result type of the called method.
 3026         </error>



 3027         <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
 3028           Thread was not suspended and was not the current thread.
 3029         </error>
 3030         <error id="JVMTI_ERROR_NO_MORE_FRAMES">
 3031           There are no more frames on the call stack.
 3032         </error>
 3033       </errors>
 3034     </function>
 3035 
 3036     <function id="ForceEarlyReturnInt" num="82" since="1.1">
 3037       <synopsis>Force Early Return - Int</synopsis>
 3038       <description>
 3039         This function can be used to return from a method whose
 3040         result type is <code>int</code>, <code>short</code>,
 3041         <code>char</code>, <code>byte</code>, or
 3042         <code>boolean</code>.
 3043       </description>
 3044       <origin>new</origin>
 3045       <capabilities>
 3046         <required id="can_force_early_return"></required>

 3055         <param id="value">
 3056           <jint/>
 3057           <description>
 3058             The return value for the called frame.
 3059           </description>
 3060         </param>
 3061       </parameters>
 3062       <errors>
 3063         <error id="JVMTI_ERROR_OPAQUE_FRAME">
 3064           Attempted to return early from a frame
 3065           corresponding to a native method.
 3066           Or the implementation is unable to provide
 3067           this functionality on this frame.
 3068         </error>
 3069         <error id="JVMTI_ERROR_TYPE_MISMATCH">
 3070           The result type of the called method is not
 3071           <code>int</code>, <code>short</code>,
 3072           <code>char</code>, <code>byte</code>, or
 3073           <code>boolean</code>.
 3074         </error>



 3075         <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
 3076           Thread was not suspended and was not the current thread.
 3077         </error>
 3078         <error id="JVMTI_ERROR_NO_MORE_FRAMES">
 3079           There are no frames on the call stack.
 3080         </error>
 3081       </errors>
 3082     </function>
 3083 
 3084     <function id="ForceEarlyReturnLong" num="83" since="1.1">
 3085       <synopsis>Force Early Return - Long</synopsis>
 3086       <description>
 3087         This function can be used to return from a method whose
 3088         result type is <code>long</code>.
 3089       </description>
 3090       <origin>new</origin>
 3091       <capabilities>
 3092         <required id="can_force_early_return"></required>
 3093       </capabilities>
 3094       <parameters>

 3098             The thread whose current frame is to return early.
 3099           </description>
 3100         </param>
 3101         <param id="value">
 3102           <jlong/>
 3103           <description>
 3104             The return value for the called frame.
 3105           </description>
 3106         </param>
 3107       </parameters>
 3108       <errors>
 3109         <error id="JVMTI_ERROR_OPAQUE_FRAME">
 3110           Attempted to return early from a frame
 3111           corresponding to a native method.
 3112           Or the implementation is unable to provide
 3113           this functionality on this frame.
 3114         </error>
 3115         <error id="JVMTI_ERROR_TYPE_MISMATCH">
 3116           The result type of the called method is not <code>long</code>.
 3117         </error>



 3118         <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
 3119           Thread was not suspended and was not the current thread.
 3120         </error>
 3121         <error id="JVMTI_ERROR_NO_MORE_FRAMES">
 3122           There are no frames on the call stack.
 3123         </error>
 3124       </errors>
 3125     </function>
 3126 
 3127     <function id="ForceEarlyReturnFloat" num="84" since="1.1">
 3128       <synopsis>Force Early Return - Float</synopsis>
 3129       <description>
 3130         This function can be used to return from a method whose
 3131         result type is <code>float</code>.
 3132       </description>
 3133       <origin>new</origin>
 3134       <capabilities>
 3135         <required id="can_force_early_return"></required>
 3136       </capabilities>
 3137       <parameters>

 3141             The thread whose current frame is to return early.
 3142           </description>
 3143         </param>
 3144         <param id="value">
 3145           <jfloat/>
 3146           <description>
 3147             The return value for the called frame.
 3148           </description>
 3149         </param>
 3150       </parameters>
 3151       <errors>
 3152         <error id="JVMTI_ERROR_OPAQUE_FRAME">
 3153           Attempted to return early from a frame
 3154           corresponding to a native method.
 3155           Or the implementation is unable to provide
 3156           this functionality on this frame.
 3157         </error>
 3158         <error id="JVMTI_ERROR_TYPE_MISMATCH">
 3159           The result type of the called method is not <code>float</code>.
 3160         </error>



 3161         <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
 3162           Thread was not suspended and was not the current thread.
 3163         </error>
 3164         <error id="JVMTI_ERROR_NO_MORE_FRAMES">
 3165           There are no frames on the call stack.
 3166         </error>
 3167       </errors>
 3168     </function>
 3169 
 3170     <function id="ForceEarlyReturnDouble" num="85" since="1.1">
 3171       <synopsis>Force Early Return - Double</synopsis>
 3172       <description>
 3173         This function can be used to return from a method whose
 3174         result type is <code>double</code>.
 3175       </description>
 3176       <origin>new</origin>
 3177       <capabilities>
 3178         <required id="can_force_early_return"></required>
 3179       </capabilities>
 3180       <parameters>

 3182           <jthread null="current"/>
 3183           <description>
 3184             The thread whose current frame is to return early.
 3185           </description>
 3186         </param>
 3187         <param id="value">
 3188           <jdouble/>
 3189           <description>
 3190             The return value for the called frame.
 3191           </description>
 3192         </param>
 3193       </parameters>
 3194       <errors>
 3195         <error id="JVMTI_ERROR_OPAQUE_FRAME">
 3196           Attempted to return early from a frame corresponding to a native method.
 3197           Or the implementation is unable to provide this functionality on this frame.
 3198         </error>
 3199         <error id="JVMTI_ERROR_TYPE_MISMATCH">
 3200           The result type of the called method is not <code>double</code>.
 3201         </error>



 3202         <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
 3203           Thread was not suspended and was not the current thread.
 3204         </error>
 3205         <error id="JVMTI_ERROR_NO_MORE_FRAMES">
 3206           There are no frames on the call stack.
 3207         </error>
 3208       </errors>
 3209     </function>
 3210 
 3211     <function id="ForceEarlyReturnVoid" num="86" since="1.1">
 3212       <synopsis>Force Early Return - Void</synopsis>
 3213       <description>
 3214         This function can be used to return from a method with no result type.
 3215         That is, the called method must be declared <code>void</code>.
 3216       </description>
 3217       <origin>new</origin>
 3218       <capabilities>
 3219         <required id="can_force_early_return"></required>
 3220       </capabilities>
 3221       <parameters>
 3222         <param id="thread">
 3223           <jthread null="current"/>
 3224           <description>
 3225             The thread whose current frame is to return early.
 3226           </description>
 3227         </param>
 3228       </parameters>
 3229       <errors>
 3230         <error id="JVMTI_ERROR_OPAQUE_FRAME">
 3231           Attempted to return early from a frame
 3232           corresponding to a native method.
 3233           Or the implementation is unable to provide
 3234           this functionality on this frame.
 3235         </error>
 3236         <error id="JVMTI_ERROR_TYPE_MISMATCH">
 3237           The called method has a result type.
 3238         </error>



 3239         <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
 3240           Thread was not suspended and was not the current thread.
 3241         </error>
 3242         <error id="JVMTI_ERROR_NO_MORE_FRAMES">
 3243           There are no frames on the call stack.
 3244         </error>
 3245       </errors>
 3246     </function>
 3247 
 3248   </category>
 3249 
 3250   <category id="Heap" label="Heap">
 3251     <intro>
 3252       These functions are used to analyze the heap.
 3253       Functionality includes the ability to view the objects in the
 3254       heap and to tag these objects.
 3255     </intro>
 3256 
 3257     <intro id="objectTags" label="Object Tags">
 3258       A <i>tag</i> is a value associated with an object.

 5679       These functions are used to retrieve or set the value of a local variable.
 5680       The variable is identified by the depth of the frame containing its
 5681       value and the variable's slot number within that frame.
 5682       The mapping of variables to
 5683       slot numbers can be obtained with the function
 5684       <functionlink id="GetLocalVariableTable"></functionlink>.
 5685     </intro>
 5686 
 5687     <function id="GetLocalObject" num="21">
 5688       <synopsis>Get Local Variable - Object</synopsis>
 5689       <description>
 5690         This function can be used to retrieve the value of a local
 5691         variable whose type is <code>Object</code> or a subclass of <code>Object</code>.
 5692       </description>
 5693       <origin>jvmdi</origin>
 5694       <capabilities>
 5695         <required id="can_access_local_variables"></required>
 5696       </capabilities>
 5697       <parameters>
 5698         <param id="thread">
 5699           <jthread null="current" frame="frame"/>
 5700           <description>
 5701             The thread of the frame containing the variable's value.
 5702           </description>
 5703         </param>
 5704         <param id="depth">
 5705           <jframeID thread="thread"/>
 5706           <description>
 5707             The depth of the frame containing the variable's value.
 5708           </description>
 5709         </param>
 5710         <param id="slot">
 5711           <jint/>
 5712           <description>
 5713             The variable's slot number.
 5714           </description>
 5715         </param>
 5716         <param id="value_ptr">
 5717           <outptr><jobject/></outptr>
 5718             <description>
 5719               On return, points to the variable's value.

 5732           Not a visible frame
 5733         </error>
 5734       </errors>
 5735     </function>
 5736 
 5737     <function id="GetLocalInstance" num="155" since="1.2">
 5738       <synopsis>Get Local Instance</synopsis>
 5739       <description>
 5740         This function can be used to retrieve the value of the local object
 5741         variable at slot 0 (the "<code>this</code>" object) from non-static
 5742         frames.  This function can retrieve the "<code>this</code>" object from
 5743         native method frames, whereas <code>GetLocalObject()</code> would
 5744         return <code>JVMTI_ERROR_OPAQUE_FRAME</code> in those cases.
 5745       </description>
 5746       <origin>new</origin>
 5747       <capabilities>
 5748         <required id="can_access_local_variables"></required>
 5749       </capabilities>
 5750       <parameters>
 5751         <param id="thread">
 5752           <jthread null="current" frame="frame"/>
 5753           <description>
 5754             The thread of the frame containing the variable's value.
 5755           </description>
 5756         </param>
 5757         <param id="depth">
 5758           <jframeID thread="thread"/>
 5759           <description>
 5760             The depth of the frame containing the variable's value.
 5761           </description>
 5762         </param>
 5763         <param id="value_ptr">
 5764           <outptr><jobject/></outptr>
 5765             <description>
 5766               On return, points to the variable's value.
 5767             </description>
 5768         </param>
 5769       </parameters>
 5770       <errors>
 5771         <error id="JVMTI_ERROR_INVALID_SLOT">
 5772           If the specified frame is a static method frame.
 5773         </error>
 5774       </errors>
 5775     </function>
 5776     <function id="GetLocalInt" num="22">
 5777       <synopsis>Get Local Variable - Int</synopsis>
 5778       <description>
 5779         This function can be used to retrieve the value of a local
 5780         variable whose type is <code>int</code>,
 5781         <code>short</code>, <code>char</code>, <code>byte</code>, or
 5782         <code>boolean</code>.
 5783       </description>
 5784       <origin>jvmdi</origin>
 5785       <capabilities>
 5786         <required id="can_access_local_variables"></required>
 5787       </capabilities>
 5788       <parameters>
 5789         <param id="thread">
 5790           <jthread null="current" frame="frame"/>
 5791           <description>
 5792             The thread of the frame containing the variable's value.
 5793           </description>
 5794         </param>
 5795         <param id="depth">
 5796           <jframeID thread="thread"/>
 5797           <description>
 5798             The depth of the frame containing the variable's value.
 5799           </description>
 5800         </param>
 5801         <param id="slot">
 5802           <jint/>
 5803           <description>
 5804             The variable's slot number.
 5805           </description>
 5806         </param>
 5807         <param id="value_ptr">
 5808           <outptr><jint/></outptr>
 5809           <description>
 5810             On return, points to the variable's value.

 5822           <code>boolean</code>.
 5823         </error>
 5824         <error id="JVMTI_ERROR_OPAQUE_FRAME">
 5825           Not a visible frame
 5826         </error>
 5827       </errors>
 5828     </function>
 5829 
 5830     <function id="GetLocalLong" num="23">
 5831       <synopsis>Get Local Variable - Long</synopsis>
 5832       <description>
 5833         This function can be used to retrieve the value of a local
 5834         variable whose type is <code>long</code>.
 5835       </description>
 5836       <origin>jvmdi</origin>
 5837       <capabilities>
 5838         <required id="can_access_local_variables"></required>
 5839       </capabilities>
 5840       <parameters>
 5841         <param id="thread">
 5842           <jthread null="current" frame="frame"/>
 5843           <description>
 5844             The thread of the frame containing the variable's value.
 5845           </description>
 5846         </param>
 5847         <param id="depth">
 5848           <jframeID thread="thread"/>
 5849           <description>
 5850             The depth of the frame containing the variable's value.
 5851           </description>
 5852         </param>
 5853         <param id="slot">
 5854           <jint/>
 5855           <description>
 5856             The variable's slot number.
 5857           </description>
 5858         </param>
 5859         <param id="value_ptr">
 5860           <outptr><jlong/></outptr>
 5861           <description>
 5862             On return, points to the variable's value.

 5871           The variable type is not <code>long</code>.
 5872         </error>
 5873         <error id="JVMTI_ERROR_OPAQUE_FRAME">
 5874           Not a visible frame
 5875         </error>
 5876       </errors>
 5877     </function>
 5878 
 5879     <function id="GetLocalFloat" num="24">
 5880       <synopsis>Get Local Variable - Float</synopsis>
 5881       <description>
 5882         This function can be used to retrieve the value of a local
 5883         variable whose type is <code>float</code>.
 5884       </description>
 5885       <origin>jvmdi</origin>
 5886       <capabilities>
 5887         <required id="can_access_local_variables"></required>
 5888       </capabilities>
 5889       <parameters>
 5890         <param id="thread">
 5891           <jthread null="current" frame="frame"/>
 5892           <description>
 5893             The thread of the frame containing the variable's value.
 5894           </description>
 5895         </param>
 5896         <param id="depth">
 5897           <jframeID thread="thread"/>
 5898           <description>
 5899             The depth of the frame containing the variable's value.
 5900           </description>
 5901         </param>
 5902         <param id="slot">
 5903           <jint/>
 5904           <description>
 5905             The variable's slot number.
 5906           </description>
 5907         </param>
 5908         <param id="value_ptr">
 5909           <outptr><jfloat/></outptr>
 5910           <description>
 5911             On return, points to the variable's value.

 5920           The variable type is not <code>float</code>.
 5921         </error>
 5922         <error id="JVMTI_ERROR_OPAQUE_FRAME">
 5923           Not a visible frame
 5924         </error>
 5925       </errors>
 5926     </function>
 5927 
 5928     <function id="GetLocalDouble" num="25">
 5929       <synopsis>Get Local Variable - Double</synopsis>
 5930       <description>
 5931         This function can be used to retrieve the value of a local
 5932         variable whose type is <code>long</code>.
 5933       </description>
 5934       <origin>jvmdi</origin>
 5935       <capabilities>
 5936         <required id="can_access_local_variables"></required>
 5937       </capabilities>
 5938       <parameters>
 5939         <param id="thread">
 5940           <jthread null="current" frame="frame"/>
 5941           <description>
 5942             The thread of the frame containing the variable's value.
 5943           </description>
 5944         </param>
 5945         <param id="depth">
 5946           <jframeID thread="thread"/>
 5947           <description>
 5948             The depth of the frame containing the variable's value.
 5949           </description>
 5950         </param>
 5951         <param id="slot">
 5952           <jint/>
 5953           <description>
 5954             The variable's slot number.
 5955           </description>
 5956         </param>
 5957         <param id="value_ptr">
 5958           <outptr><jdouble/></outptr>
 5959           <description>
 5960             On return, points to the variable's value.

10410       </capabilityfield>
10411       <capabilityfield id="can_generate_early_class_hook_events" since="9">
10412         <description>
10413           Can generate the <eventlink id="ClassFileLoadHook"/> events
10414           in the primordial phase. If this capability and
10415           <internallink id="jvmtiCapabilities.can_generate_all_class_hook_events">
10416           <code>can_generate_all_class_hook_events</code></internallink>
10417           are enabled then the <eventlink id="ClassFileLoadHook"/> events
10418           can be posted for classes loaded in the primordial phase.
10419           See <eventlink id="ClassFileLoadHook"/>.
10420         </description>
10421       </capabilityfield>
10422       <capabilityfield id="can_generate_sampled_object_alloc_events" since="11">
10423         <description>
10424           Can generate sampled allocation events.
10425           If this capability is enabled then the heap sampling method
10426           <functionlink id="SetHeapSamplingInterval"></functionlink> can be
10427           called and <eventlink id="SampledObjectAlloc"></eventlink> events can be generated.
10428         </description>
10429       </capabilityfield>















10430     </capabilitiestypedef>
10431 
10432     <function id="GetPotentialCapabilities" jkernel="yes" phase="onload" num="140">
10433       <synopsis>Get Potential Capabilities</synopsis>
10434       <description>
10435         Returns via <paramlink id="capabilities_ptr"></paramlink> the <jvmti/>
10436         features that can potentially be possessed by this environment
10437         at this time.
10438         The returned capabilities differ from the complete set of capabilities
10439         implemented by the VM in two cases: another environment possesses
10440         capabilities that can only be possessed by one environment, or the
10441         current <functionlink id="GetPhase">phase</functionlink> is live,
10442         and certain capabilities can only be added during the <code>OnLoad</code> phase.
10443         The <functionlink id="AddCapabilities"></functionlink> function
10444         may be used to set any or all or these capabilities.
10445         Currently possessed capabilities are included.
10446         <p/>
10447         Typically this function is used in the <code>OnLoad</code> function.
10448         Some virtual machines may allow a limited set of capabilities to be
10449         added in the live phase.

10767         </param>
10768       </parameters>
10769       <errors>
10770       </errors>
10771     </function>
10772 
10773     <function id="GetCurrentThreadCpuTime" callbacksafe="safe" impl="innative notrace" phase="start" num="135">
10774       <synopsis>Get Current Thread CPU Time</synopsis>
10775       <description>
10776             Return the CPU time utilized by the current thread.
10777             <p/>
10778             Note that the <functionlink id="GetThreadCpuTime"/>
10779             function provides CPU time for any thread, including
10780             the current thread. <code>GetCurrentThreadCpuTime</code>
10781             exists to support platforms which cannot
10782             supply CPU time for threads other than the current
10783             thread or which have more accurate information for
10784             the current thread (see
10785             <functionlink id="GetCurrentThreadCpuTimerInfo"/> vs
10786             <functionlink id="GetThreadCpuTimerInfo"/>).


10787             On many platforms this call will be equivalent to:
10788 <example>
10789   GetThreadCpuTime(env, NULL, nanos_ptr)
10790 </example>
10791       </description>
10792       <origin>new</origin>
10793       <capabilities>
10794         <required id="can_get_current_thread_cpu_time">
10795             Can get current thread CPU time.
10796             <p/>
10797             If this capability is enabled after threads have started,
10798             the implementation may choose any time up
10799             to and including the time that the capability is enabled
10800             as the point where CPU time collection starts.
10801             <p/>
10802             This capability must be potentially available on any
10803             platform where
10804             <internallink id="jvmtiCapabilities.can_get_thread_cpu_time"><code>can_get_thread_cpu_time</code></internallink>
10805             is potentially available.
10806         </required>
10807       </capabilities>
10808       <parameters>
10809         <param id="nanos_ptr">
10810           <outptr><jlong/></outptr>
10811           <description>
10812             On return, points to the CPU time used by this thread
10813             in nanoseconds.
10814             This is an unsigned value.  If tested or printed as a jlong (signed value)
10815             it may appear to be a negative number.
10816           </description>
10817         </param>
10818       </parameters>
10819       <errors>



10820       </errors>
10821     </function>
10822 
10823     <function id="GetThreadCpuTimerInfo" num="136">
10824       <synopsis>Get Thread CPU Timer Information</synopsis>
10825       <description>
10826         Get information about the
10827         <functionlink id="GetThreadCpuTime"/> timer.
10828         The fields of the <datalink id="jvmtiTimerInfo"/> structure
10829         are filled in with details about the timer.
10830         This information is specific to the platform and the implementation of
10831         <functionlink id="GetThreadCpuTime"/> and thus
10832         does not vary by thread nor does it vary
10833         during a particular invocation of the VM.
10834         <p/>
10835         Note that the implementations of <functionlink id="GetCurrentThreadCpuTime"/>
10836         and <functionlink id="GetThreadCpuTime"/> may differ, and thus the values
10837         returned by <functionlink id="GetCurrentThreadCpuTimerInfo"/>
10838         and <code>GetThreadCpuTimerInfo</code>
10839         may differ -- see <functionlink id="GetCurrentThreadCpuTime"/> for more information.

10864           <p/>
10865           Get information about this timer with
10866           <functionlink id="GetThreadCpuTimerInfo"/>.
10867       </description>
10868       <origin>new</origin>
10869       <capabilities>
10870         <required id="can_get_thread_cpu_time">
10871             Can get thread CPU time.
10872             <p/>
10873             If this capability is enabled after threads have started,
10874             the implementation may choose any time up
10875             to and including the time that the capability is enabled
10876             as the point where CPU time collection starts.
10877         </required>
10878       </capabilities>
10879       <parameters>
10880         <param id="thread">
10881           <jthread null="current"/>
10882             <description>
10883               The thread to query.
10884             </description>


10885         </param>
10886         <param id="nanos_ptr">
10887           <outptr><jlong/></outptr>
10888           <description>
10889             On return, points to the CPU time used by the specified thread
10890             in nanoseconds.
10891             This is an unsigned value.  If tested or printed as a jlong (signed value)
10892             it may appear to be a negative number.
10893           </description>
10894         </param>
10895       </parameters>
10896       <errors>



10897       </errors>
10898     </function>
10899 
10900     <function id="GetTimerInfo" phase="any" callbacksafe="safe" num="138">
10901       <synopsis>Get Timer Information</synopsis>
10902       <description>
10903         Get information about the
10904         <functionlink id="GetTime"/> timer.
10905         The fields of the <datalink id="jvmtiTimerInfo"/> structure
10906         are filled in with details about the timer.
10907         This information will not change during a particular invocation of the VM.
10908       </description>
10909       <origin>new</origin>
10910       <capabilities>
10911       </capabilities>
10912       <parameters>
10913         <param id="info_ptr">
10914           <outptr><struct>jvmtiTimerInfo</struct></outptr>
10915           <description>
10916             On return, filled with information describing the time

12674           </description>
12675       </param>
12676       <param id="location">
12677         <jlocation/>
12678         <description>
12679           Location where exception is being caught
12680         </description>
12681       </param>
12682       <param id="exception">
12683         <jobject/>
12684           <description>
12685             Exception being caught
12686           </description>
12687       </param>
12688     </parameters>
12689   </event>
12690 
12691   <event label="Thread Start"
12692          id="ThreadStart" const="JVMTI_EVENT_THREAD_START" num="52" phase="start">
12693     <description>
12694       Thread start events are generated by a new thread before its initial
12695       method executes.







12696       <p/>
12697       A thread may be listed in the array returned by
12698       <functionlink id="GetAllThreads"></functionlink>
12699       before its thread start event is generated.
12700       It is possible for other events to be generated
12701       on a thread before its thread start event.
12702       <p/>
12703       The event is sent on the newly started <paramlink id="thread"></paramlink>.
12704     </description>
12705     <origin>jvmdi</origin>
12706     <capabilities>
12707     </capabilities>
12708     <parameters>
12709       <param id="jni_env">
12710         <outptr>
12711           <struct>JNIEnv</struct>
12712         </outptr>
12713           <description>
12714             The JNI environment of the event (current) thread.
12715           </description>
12716       </param>
12717       <param id="thread">
12718         <jthread/>
12719           <description>
12720             Thread starting
12721           </description>
12722       </param>
12723     </parameters>
12724   </event>
12725 
12726   <event label="Thread End"
12727          id="ThreadEnd" const="JVMTI_EVENT_THREAD_END" filtered="thread" num="53" phase="start">
12728     <description>
12729       Thread end events are generated by a terminating thread
12730       after its initial method has finished execution.








12731       <p/>
12732       A thread may be listed in the array returned by
12733       <functionlink id="GetAllThreads"></functionlink>
12734       after its thread end event is generated.
12735       No events are generated on a thread
12736       after its thread end event.
12737       <p/>
12738       The event is sent on the dying <paramlink id="thread"></paramlink>.
12739     </description>
12740     <origin>jvmdi</origin>
12741     <capabilities>
12742     </capabilities>
12743     <parameters>
12744       <param id="jni_env">
12745         <outptr>
12746           <struct>JNIEnv</struct>
12747         </outptr>
12748           <description>
12749             The JNI environment of the event (current) thread.
12750           </description>
12751       </param>
12752       <param id="thread">
12753         <jthread/>
12754           <description>
12755             Thread ending
12756           </description>
12757       </param>
12758     </parameters>
12759   </event>
12760 
































































































































12761   <event label="Class Load"
12762          id="ClassLoad" const="JVMTI_EVENT_CLASS_LOAD" filtered="thread" phase="start" num="55">
12763     <description>
12764       A class load event is generated
12765       <functionlink id="GetLoadedClasses">when a class or interface is created.</functionlink>.
12766       <p/>
12767       Array class creation does not generate a class load event.
12768       The creation of a primitive class (for example, java.lang.Integer.TYPE)
12769       does not generate a class load event.
12770       <p/>
12771       The order of class load events generated by a particular thread is guaranteed
12772       to match the order of class loading within that thread.
12773       <p/>
12774       This event is sent at an early stage in loading the class. As
12775       a result the class should be used carefully.  Note, for example,
12776       that methods and fields are not yet loaded, so queries for methods,
12777       fields, subclasses, and so on will not give correct results.
12778       See "Loading of Classes and Interfaces" in the <i>Java Language
12779       Specification</i>.  For most
12780       purposes the <eventlink id="ClassPrepare"></eventlink> event will

  117 
  118    <!ELEMENT jclass EMPTY>
  119    <!ATTLIST jclass method CDATA #IMPLIED
  120                     field  CDATA #IMPLIED>
  121 
  122    <!ELEMENT jframeID EMPTY>
  123    <!ATTLIST jframeID thread CDATA #IMPLIED>
  124 
  125    <!ELEMENT jrawMonitorID EMPTY>
  126 
  127    <!ELEMENT jthread EMPTY>
  128    <!ATTLIST jthread started CDATA #IMPLIED
  129                      null CDATA #IMPLIED
  130                      frame CDATA #IMPLIED
  131                      impl CDATA #IMPLIED>
  132 
  133    <!ELEMENT varargs EMPTY>
  134 
  135    <!ELEMENT jthreadGroup EMPTY>
  136    <!ELEMENT jobject EMPTY>
  137    <!ATTLIST jobject frame CDATA #IMPLIED>
  138 
  139    <!ELEMENT jvalue EMPTY>
  140    <!ELEMENT jchar EMPTY>
  141    <!ELEMENT jint EMPTY>
  142    <!ATTLIST jint min CDATA #IMPLIED>
  143    <!ELEMENT jlong EMPTY>
  144    <!ELEMENT jfloat EMPTY>
  145    <!ELEMENT jdouble EMPTY>
  146    <!ELEMENT jlocation EMPTY>
  147    <!ELEMENT jboolean EMPTY>
  148    <!ELEMENT char EMPTY>
  149    <!ELEMENT uchar EMPTY>
  150    <!ELEMENT size_t EMPTY>
  151    <!ELEMENT void EMPTY>
  152    <!ELEMENT enum (#PCDATA)*>
  153    <!ELEMENT struct (#PCDATA)*>
  154 
  155    <!ELEMENT nullok ANY>
  156 
  157    <!ELEMENT ptrtype     ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
  158                                    jthreadGroup|jobject|jvalue), nullok?)>

 1113       <parameters>
 1114         <param id="mem">
 1115           <outbuf>
 1116             <uchar/>
 1117             <nullok>the call is ignored</nullok>
 1118           </outbuf>
 1119           <description>
 1120             A pointer to the beginning of the allocated memory.
 1121             Please ignore "On return, the elements are set."
 1122               <todo>keep it from generating "On return, the elements are set"</todo>
 1123           </description>
 1124         </param>
 1125       </parameters>
 1126       <errors>
 1127       </errors>
 1128     </function>
 1129   </category>
 1130 
 1131   <category id="threadCategory" label="Thread">
 1132     <intro>
 1133         These functions provide information about threads and allow an agent to
 1134         suspend and resume threads.
 1135         <p/>
 1136         The <code>jthread</code> specified to these functions can be a JNI
 1137         reference to a
 1138         <externallink id="../api/java.base/java/lang/Thread.html#platform-threads">platform thread</externallink>
 1139         or <externallink id="../api/java.base/java/lang/Thread.html#virtual-threads">virtual thread</externallink>.
 1140         Some functions are not supported on virtual threads and return
 1141         <code>JVMTI_ERROR_INVALID_THREAD</code> when called with a reference
 1142         to a virtual thread.
 1143     </intro>
 1144 
 1145     <function id="GetThreadState" num="17">
 1146       <synopsis>Get Thread State</synopsis>
 1147       <description>
 1148         Get the state of a thread.  The state of the thread is represented by the
 1149         answers to the hierarchical set of questions below:
 1150           <ul type="circle">
 1151             <li><i>Alive?</i>
 1152               <ul>
 1153                 <li>Not alive.
 1154                   <ul type="circle">
 1155                     <li><i>Why not alive?</i>
 1156                       <ul>
 1157                         <li>New.</li>
 1158                         <li>Terminated (<datalink
 1159                             id="JVMTI_THREAD_STATE_TERMINATED"><code>JVMTI_THREAD_STATE_TERMINATED</code></datalink>)</li>
 1160                       </ul>
 1161                     </li>
 1162                   </ul>

 1217                       </ul>
 1218                     </li>
 1219                   </ul>
 1220                 </li>
 1221               </ul>
 1222             </li>
 1223           </ul>
 1224         <p/>
 1225         The answers are represented by the following bit vector.
 1226         <constants id="jvmtiThreadState" label="Thread State Flags" kind="bits">
 1227           <constant id="JVMTI_THREAD_STATE_ALIVE" num="0x0001">
 1228             Thread is alive. Zero if thread is new (not started) or terminated.
 1229           </constant>
 1230           <constant id="JVMTI_THREAD_STATE_TERMINATED" num="0x0002">
 1231             Thread has completed execution.
 1232           </constant>
 1233           <constant id="JVMTI_THREAD_STATE_RUNNABLE" num="0x0004">
 1234             Thread is runnable.
 1235           </constant>
 1236           <constant id="JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER" num="0x0400">
 1237             Thread is waiting to enter a synchronized block/method or,
 1238             after an <code>Object.wait()</code>, waiting to re-enter a
 1239             synchronized block/method.
 1240           </constant>
 1241           <constant id="JVMTI_THREAD_STATE_WAITING" num="0x0080">
 1242             Thread is waiting.
 1243           </constant>
 1244           <constant id="JVMTI_THREAD_STATE_WAITING_INDEFINITELY" num="0x0010">
 1245             Thread is waiting without a timeout.
 1246             For example, <code>Object.wait()</code>.
 1247           </constant>
 1248           <constant id="JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT" num="0x0020">
 1249             Thread is waiting with a maximum time to wait specified.
 1250             For example, <code>Object.wait(long)</code>.
 1251           </constant>
 1252           <constant id="JVMTI_THREAD_STATE_SLEEPING" num="0x0040">
 1253             Thread is sleeping -- <code>Thread.sleep</code>.
 1254           </constant>
 1255           <constant id="JVMTI_THREAD_STATE_IN_OBJECT_WAIT" num="0x0100">
 1256             Thread is waiting on an object monitor -- <code>Object.wait</code>.
 1257           </constant>
 1258           <constant id="JVMTI_THREAD_STATE_PARKED" num="0x0200">
 1259             Thread is parked, for example: <code>LockSupport.park</code>,
 1260             <code>LockSupport.parkUtil</code> and <code>LockSupport.parkNanos</code>.
 1261             A virtual thread that is sleeping, in <code>Thread.sleep</code>, may
 1262             have this state flag set instead of <code>JVMTI_THREAD_STATE_SLEEPING</code>.
 1263           </constant>
 1264           <constant id="JVMTI_THREAD_STATE_SUSPENDED" num="0x100000">
 1265             Thread suspended.
 1266             <code>java.lang.Thread.suspend()</code>
 1267             or a <jvmti/> suspend function
 1268             (such as <functionlink id="SuspendThread"></functionlink>)
 1269             has been called on the thread. If this bit
 1270             is set, the other bits refer to the thread state before suspension.
 1271           </constant>
 1272           <constant id="JVMTI_THREAD_STATE_INTERRUPTED" num="0x200000">
 1273             Thread has been interrupted.
 1274           </constant>
 1275           <constant id="JVMTI_THREAD_STATE_IN_NATIVE" num="0x400000">
 1276             Thread is in native code--that is, a native method is running
 1277             which has not called back into the VM or Java programming
 1278             language code.
 1279             <p/>
 1280             This flag is not set when running VM compiled Java programming
 1281             language code nor is it set when running VM code or
 1282             VM support code. Native VM interface functions, such as JNI and

 1510         the current thread.
 1511       </description>
 1512       <origin>new</origin>
 1513       <capabilities>
 1514       </capabilities>
 1515       <parameters>
 1516         <param id="thread_ptr">
 1517           <outptr><jthread/></outptr>
 1518           <description>
 1519              On return, points to the current thread, or <code>NULL</code>.
 1520           </description>
 1521         </param>
 1522       </parameters>
 1523       <errors>
 1524       </errors>
 1525     </function>
 1526 
 1527     <function id="GetAllThreads" num="4">
 1528       <synopsis>Get All Threads</synopsis>
 1529       <description>
 1530         Get all live platform threads that are attached to the VM.
 1531         The list of threads includes
 1532         <internallink id="RunAgentThread">agent threads</internallink>.
 1533         It does not include virtual threads.
 1534         A thread is live if <code>java.lang.Thread.isAlive()</code>
 1535         would return <code>true</code>, that is, the thread has
 1536         been started and has not yet died.
 1537         The universe of threads is determined by the context of the <jvmti/>
 1538         environment, which typically is all threads attached to the VM.


 1539       </description>
 1540       <origin>jvmdi</origin>
 1541       <capabilities>
 1542       </capabilities>
 1543       <parameters>
 1544         <param id="threads_count_ptr">
 1545           <outptr><jint/></outptr>
 1546           <description>
 1547             On return, points to the number of threads.
 1548           </description>
 1549         </param>
 1550         <param id="threads_ptr">
 1551           <allocbuf outcount="threads_count_ptr"><jthread/></allocbuf>
 1552             <description>
 1553               On return, points to an array of references, one
 1554               for each thread.
 1555             </description>
 1556         </param>
 1557       </parameters>
 1558       <errors>
 1559       </errors>
 1560     </function>
 1561 
 1562     <function id="SuspendThread" num="5">
 1563       <synopsis>Suspend Thread</synopsis>
 1564       <description>
 1565         Suspend the specified thread. If the calling thread is specified,
 1566         this function will not return until some other thread calls
 1567         <functionlink id="ResumeThread"></functionlink>.
 1568         If the thread is currently suspended, this function
 1569         does nothing and returns an error.
 1570       </description>
 1571       <origin>jvmdi</origin>
 1572       <capabilities>
 1573         <required id="can_suspend"></required>
 1574       </capabilities>
 1575       <parameters>
 1576         <param id="thread">
 1577           <jthread null="current" impl="noconvert"/>
 1578             <description>
 1579               The thread to suspend.
 1580             </description>
 1581         </param>
 1582       </parameters>
 1583       <errors>
 1584         <error id="JVMTI_ERROR_THREAD_SUSPENDED">
 1585           Thread already suspended.
 1586         </error>
 1587       </errors>
 1588     </function>
 1589 
 1590     <elide>
 1591     <function id="SuspendAllThreads" num="101">
 1592       <synopsis>Suspend All Threads</synopsis>
 1593       <description>
 1594         <issue>
 1595             There has been no explicit call for this function, and it will
 1596             thus be removed if there is no interest.
 1597         </issue>

 1708         </param>
 1709         <param id="results">
 1710           <outbuf incount="request_count"><enum>jvmtiError</enum></outbuf>
 1711           <description>
 1712             An agent supplied array of
 1713             <paramlink id="request_count"></paramlink> elements.
 1714             On return, filled with the error code for
 1715             the suspend of the corresponding thread.
 1716             The error code will be
 1717             <errorlink id="JVMTI_ERROR_NONE"></errorlink>
 1718             if the thread was suspended by this call.
 1719             Possible error codes are those specified
 1720             for <functionlink id="SuspendThread"></functionlink>.
 1721           </description>
 1722         </param>
 1723       </parameters>
 1724       <errors>
 1725       </errors>
 1726     </function>
 1727 
 1728     <function id="SuspendAllVirtualThreads" num="118" since="16">
 1729       <synopsis>Suspend All Virtual Threads</synopsis>
 1730       <description>
 1731         <b> SuspendAllVirtualThreads is a preview API of the Java platform. </b>
 1732         <i>Preview features may be removed in a future release, or upgraded to
 1733         permanent features of the Java platform.</i>.
 1734         <p/>
 1735         Suspend all virtual threads except those already suspended.
 1736         Virtual threads may be resumed with
 1737         <functionlink id="ResumeAllVirtualThreads"></functionlink> or
 1738         <functionlink id="ResumeThreadList"></functionlink> or
 1739         <functionlink id="ResumeThread"></functionlink>.
 1740         Virtual threads that are currently suspended do not change state.
 1741       </description>
 1742       <origin>new</origin>
 1743       <capabilities>
 1744         <required id="can_suspend"></required>
 1745         <required id="can_support_virtual_threads"></required>
 1746       </capabilities>
 1747       <parameters>
 1748         <param id="except_count">
 1749           <jint min="0"/>
 1750           <description>
 1751             The number of threads in the list of threads not to be suspended.
 1752           </description>
 1753         </param>
 1754         <param id="except_list">
 1755             <inbuf incount="except_count">
 1756               <jthread/>
 1757               <nullok>not an error if <code>except_count == 0</code></nullok>
 1758             </inbuf>
 1759             <description>
 1760               The list of threads not to be suspended.
 1761             </description>
 1762         </param>
 1763       </parameters>
 1764       <errors>
 1765         <error id="JVMTI_ERROR_INVALID_THREAD">
 1766           A thread in <paramlink id="except_list"></paramlink> was invalid.
 1767         </error>
 1768         <error id="JVMTI_ERROR_NULL_POINTER">
 1769           Both <paramlink id="except_list"></paramlink> was <code>NULL</code>
 1770           and <paramlink id="except_count"></paramlink> was non-zero.
 1771         </error>
 1772       </errors>
 1773     </function>
 1774 
 1775     <function id="ResumeThread" num="6">
 1776       <synopsis>Resume Thread</synopsis>
 1777       <description>
 1778         Resume a suspended thread.
 1779         Any threads currently suspended through
 1780         a <jvmti/> suspend function (eg.
 1781         <functionlink id="SuspendThread"></functionlink>)
 1782         or <code>java.lang.Thread.suspend()</code>
 1783         will resume execution;
 1784         all other threads are unaffected.
 1785       </description>
 1786       <origin>jvmdi</origin>
 1787       <capabilities>
 1788         <required id="can_suspend"></required>
 1789       </capabilities>
 1790       <parameters>
 1791         <param id="thread">
 1792           <jthread impl="noconvert"/>
 1793             <description>
 1794               The thread to resume.
 1795             </description>
 1796         </param>
 1797       </parameters>
 1798       <errors>
 1799         <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
 1800           Thread was not suspended.
 1801         </error>
 1802         <error id="JVMTI_ERROR_INVALID_TYPESTATE">
 1803           The state of the thread has been modified, and is now inconsistent.
 1804         </error>
 1805       </errors>
 1806     </function>
 1807 
 1808     <function id="ResumeThreadList" num="93">
 1809       <synopsis>Resume Thread List</synopsis>
 1810       <description>
 1811         Resume the <paramlink id="request_count"></paramlink>
 1812         threads specified in the

 1836         </param>
 1837         <param id="results">
 1838           <outbuf incount="request_count"><enum>jvmtiError</enum></outbuf>
 1839           <description>
 1840             An agent supplied array of
 1841             <paramlink id="request_count"></paramlink> elements.
 1842             On return, filled with the error code for
 1843             the resume of the corresponding thread.
 1844             The error code will be
 1845             <errorlink id="JVMTI_ERROR_NONE"></errorlink>
 1846             if the thread was suspended by this call.
 1847             Possible error codes are those specified
 1848             for <functionlink id="ResumeThread"></functionlink>.
 1849           </description>
 1850         </param>
 1851       </parameters>
 1852       <errors>
 1853       </errors>
 1854     </function>
 1855 
 1856    <function id="ResumeAllVirtualThreads" num="119" since="16">
 1857       <synopsis>Resume All Virtual Threads</synopsis>
 1858       <description>
 1859         <b> SuspendAllVirtualThreads is a preview API of the Java platform. </b>
 1860         <i>Preview features may be removed in a future release, or upgraded to
 1861         permanent features of the Java platform.</i>.
 1862         <p/>
 1863         Resume all virtual threads except those already resumed.
 1864         Virtual threads may be suspended with
 1865         <functionlink id="SuspendAllVirtualThreads"></functionlink> or
 1866         <functionlink id="SuspendThreadList"></functionlink> or
 1867         <functionlink id="SuspendThread"></functionlink>.
 1868         Virtual threads that are currently resumed do not change state.
 1869       </description>
 1870       <origin>new</origin>
 1871       <capabilities>
 1872         <required id="can_suspend"></required>
 1873         <required id="can_support_virtual_threads"></required>
 1874       </capabilities>
 1875       <parameters>
 1876         <param id="except_count">
 1877           <jint min="0"/>
 1878           <description>
 1879             The number of threads in the list of threads not to be resumed.
 1880           </description>
 1881         </param>
 1882         <param id="except_list">
 1883             <inbuf incount="except_count">
 1884               <jthread/>
 1885               <nullok>not an error if <code>except_count == 0</code></nullok>
 1886             </inbuf>
 1887             <description>
 1888               The list of threads not to be resumed.
 1889             </description>
 1890         </param>
 1891       </parameters>
 1892       <errors>
 1893         <error id="JVMTI_ERROR_INVALID_THREAD">
 1894           A thread in <paramlink id="except_list"></paramlink> was invalid.
 1895         </error>
 1896         <error id="JVMTI_ERROR_NULL_POINTER">
 1897           Both <paramlink id="except_list"></paramlink> was <code>NULL</code>
 1898           and <paramlink id="except_count"></paramlink> was non-zero.
 1899         </error>
 1900       </errors>
 1901     </function>
 1902 
 1903     <function id="StopThread" num="7">
 1904       <synopsis>Stop Thread</synopsis>
 1905       <description>
 1906         Send the specified asynchronous exception to the specified platform thread.
 1907         Normally, this function is used to kill the specified thread with an
 1908         instance of the exception <code>ThreadDeath</code>, similar to
 1909         <code>java.lang.Thread.stop</code>.
 1910       </description>
 1911       <origin>jvmdi</origin>
 1912       <capabilities>
 1913         <required id="can_signal_thread"></required>
 1914       </capabilities>
 1915       <parameters>
 1916         <param id="thread">
 1917           <jthread/>
 1918             <description>
 1919               The thread to stop.
 1920               The <code>thread</code> may not be a virtual thread. Otherwise, the error code
 1921               <errorlink id="JVMTI_ERROR_INVALID_THREAD"></errorlink> will be returned.
 1922              </description>
 1923         </param>
 1924         <param id="exception">
 1925           <jobject/>
 1926             <description>
 1927               The asynchronous exception object.
 1928             </description>
 1929         </param>
 1930       </parameters>
 1931       <errors>
 1932         <error id="JVMTI_ERROR_INVALID_THREAD">
 1933           <paramlink id="thread"/> is a virtual thread.
 1934         </error>
 1935       </errors>
 1936     </function>
 1937 
 1938     <function id="InterruptThread" num="8">
 1939       <synopsis>Interrupt Thread</synopsis>
 1940       <description>
 1941         Interrupt the specified thread
 1942         (similar to <code>java.lang.Thread.interrupt</code>).
 1943       </description>
 1944       <origin>jvmdi</origin>
 1945       <capabilities>
 1946         <required id="can_signal_thread"></required>
 1947       </capabilities>
 1948       <parameters>
 1949         <param id="thread">
 1950           <jthread impl="noconvert"/>
 1951             <description>
 1952               The thread to interrupt.
 1953             </description>
 1954         </param>
 1955       </parameters>
 1956       <errors>
 1957       </errors>
 1958     </function>
 1959 
 1960     <function id="GetThreadInfo" num="9">
 1961       <synopsis>Get Thread Info</synopsis>
 1962       <typedef id="jvmtiThreadInfo" label="Thread information structure">
 1963         <field id="name">
 1964           <allocfieldbuf><char/></allocfieldbuf>
 1965           <description>
 1966             The thread name, encoded as a
 1967             <internallink id="mUTF">modified UTF-8</internallink> string.
 1968           </description>
 1969         </field>
 1970         <field id="priority">
 1971           <jint/>
 1972           <description>
 1973             The thread priority.  See the thread priority constants:
 1974             <datalink id="jvmtiThreadPriority"></datalink>. The priority of a
 1975             virtual thread is always <code>JVMTI_THREAD_NORM_PRIORITY</code>.
 1976           </description>
 1977         </field>
 1978         <field id="is_daemon">
 1979           <jboolean/>
 1980           <description>
 1981             Is this a daemon thread? The daemon status of a virtual thread is
 1982             always <code>JNI_TRUE</code>.
 1983           </description>
 1984         </field>
 1985         <field id="thread_group">
 1986           <jthreadGroup/>
 1987           <description>
 1988             The thread group to which this thread belongs.
 1989             <code>NULL</code> if the thread has died.
 1990           </description>
 1991         </field>
 1992         <field id="context_class_loader">
 1993           <jobject/>
 1994             <description>
 1995               The context class loader associated with this thread.
 1996             </description>
 1997         </field>
 1998       </typedef>
 1999       <description>
 2000         Get thread information. The fields of the <datalink id="jvmtiThreadInfo"/> structure
 2001         are filled in with details of the specified thread.
 2002       </description>

 2016             On return, filled with information describing the specified thread.
 2017           </description>
 2018         </param>
 2019       </parameters>
 2020       <errors>
 2021       </errors>
 2022     </function>
 2023 
 2024     <function id="GetOwnedMonitorInfo" num="10">
 2025       <synopsis>Get Owned Monitor Info</synopsis>
 2026       <description>
 2027         Get information about the monitors owned by the
 2028         specified thread.
 2029       </description>
 2030       <origin>jvmdiClone</origin>
 2031       <capabilities>
 2032         <required id="can_get_owned_monitor_info"></required>
 2033       </capabilities>
 2034       <parameters>
 2035         <param id="thread">
 2036           <jthread null="current" impl="noconvert"/>
 2037             <description>
 2038               The thread to query.
 2039             </description>
 2040         </param>
 2041         <param id="owned_monitor_count_ptr">
 2042           <outptr><jint/></outptr>
 2043           <description>
 2044             The number of monitors returned.
 2045           </description>
 2046         </param>
 2047         <param id="owned_monitors_ptr">
 2048           <allocbuf outcount="owned_monitor_count_ptr"><jobject/></allocbuf>
 2049             <description>
 2050               The array of owned monitors.
 2051             </description>
 2052         </param>
 2053       </parameters>
 2054       <errors>
 2055       </errors>
 2056     </function>

 2070           <description>
 2071             The stack depth.  Corresponds to the stack depth used in the
 2072             <internallink id="stack">Stack Frame functions</internallink>.
 2073             That is, zero is the current frame, one is the frame which
 2074             called the current frame. And it is negative one if the
 2075             implementation cannot determine the stack depth (e.g., for
 2076             monitors acquired by JNI <code>MonitorEnter</code>).
 2077           </description>
 2078         </field>
 2079       </typedef>
 2080       <description>
 2081         Get information about the monitors owned by the
 2082         specified thread and the depth of the stack frame which locked them.
 2083       </description>
 2084       <origin>new</origin>
 2085       <capabilities>
 2086         <required id="can_get_owned_monitor_stack_depth_info"></required>
 2087       </capabilities>
 2088       <parameters>
 2089         <param id="thread">
 2090           <jthread null="current" impl="noconvert"/>
 2091             <description>
 2092               The thread to query.
 2093             </description>
 2094         </param>
 2095         <param id="monitor_info_count_ptr">
 2096           <outptr><jint/></outptr>
 2097           <description>
 2098             The number of monitors returned.
 2099           </description>
 2100         </param>
 2101         <param id="monitor_info_ptr">
 2102           <allocbuf outcount="monitor_info_count_ptr">
 2103             <struct>jvmtiMonitorStackDepthInfo</struct>
 2104           </allocbuf>
 2105           <description>
 2106             The array of owned monitor depth information.
 2107           </description>
 2108         </param>
 2109       </parameters>
 2110       <errors>
 2111       </errors>
 2112     </function>
 2113 
 2114     <function id="GetCurrentContendedMonitor" num="11">
 2115       <synopsis>Get Current Contended Monitor</synopsis>
 2116       <description>
 2117         Get the object, if any, whose monitor the specified thread is waiting to
 2118         enter or waiting to regain through <code>java.lang.Object.wait</code>.
 2119       </description>
 2120       <origin>jvmdi</origin>
 2121       <capabilities>
 2122         <required id="can_get_current_contended_monitor"></required>
 2123       </capabilities>
 2124       <parameters>
 2125         <param id="thread">
 2126           <jthread null="current" impl="noconvert"/>
 2127             <description>
 2128               The thread to query.
 2129             </description>
 2130         </param>
 2131         <param id="monitor_ptr">
 2132           <outptr><jobject/></outptr>
 2133             <description>
 2134               On return, filled with the current contended monitor, or
 2135               NULL if there is none.
 2136             </description>
 2137         </param>
 2138       </parameters>
 2139       <errors>
 2140       </errors>
 2141     </function>
 2142 
 2143     <callback id="jvmtiStartFunction">
 2144       <void/>
 2145       <synopsis>Agent Start Function</synopsis>
 2146       <description>

 2220         group at either the Java programming language or <jvmti/> levels.
 2221         <p/>
 2222         The thread is not visible to Java programming language queries but is
 2223         included in <jvmti/> queries (for example,
 2224         <functionlink id="GetAllThreads"/> and
 2225         <functionlink id="GetAllStackTraces"/>).
 2226         <p/>
 2227         Upon execution of <code>proc</code>, the new thread will be attached to the
 2228         VM -- see the JNI documentation on
 2229         <externallink id="jni/invocation.html#attaching-to-the-vm"
 2230                       >Attaching to the VM</externallink>.
 2231       </description>
 2232       <origin>jvmdiClone</origin>
 2233       <capabilities>
 2234       </capabilities>
 2235       <parameters>
 2236         <param id="thread">
 2237           <jthread impl="noconvert" started="no"/>
 2238             <description>
 2239               The thread to run.
 2240               The <code>thread</code> may not be a virtual thread. Otherwise, the error code
 2241               <errorlink id="JVMTI_ERROR_INVALID_THREAD"></errorlink> will be returned.
 2242              </description>
 2243         </param>
 2244         <param id="proc">
 2245           <ptrtype>
 2246             <struct>jvmtiStartFunction</struct>
 2247           </ptrtype>
 2248           <description>
 2249             The start function.
 2250           </description>
 2251         </param>
 2252         <param id="arg">
 2253           <inbuf>
 2254             <void/>
 2255             <nullok><code>NULL</code> is passed to the start function</nullok>
 2256           </inbuf>
 2257           <description>
 2258             The argument to the start function.
 2259           </description>
 2260         </param>
 2261         <param id="priority">
 2262           <jint/>
 2263           <description>
 2264             The priority of the started thread. Any thread
 2265             priority allowed by <code>java.lang.Thread.setPriority</code> can be used including
 2266             those in <datalink id="jvmtiThreadPriority"></datalink>.
 2267           </description>
 2268         </param>
 2269       </parameters>
 2270       <errors>
 2271         <error id="JVMTI_ERROR_INVALID_PRIORITY">
 2272             <paramlink id="priority"/> is less than
 2273             <datalink id="JVMTI_THREAD_MIN_PRIORITY"/>
 2274               or greater than
 2275             <datalink id="JVMTI_THREAD_MAX_PRIORITY"/>
 2276         </error>
 2277         <error id="JVMTI_ERROR_INVALID_THREAD">
 2278           <paramlink id="thread"/> is a virtual thread.
 2279         </error>
 2280       </errors>
 2281     </function>
 2282 
 2283     <function id="SetThreadLocalStorage" jkernel="yes" impl="notrace" phase="start" num="103">
 2284       <synopsis>Set Thread Local Storage</synopsis>
 2285       <description>
 2286         The VM stores a pointer value associated with each environment-thread
 2287         pair. This pointer value is called <i>thread-local storage</i>.
 2288         This value is <code>NULL</code> unless set with this function.
 2289         Agents can allocate memory in which they store thread specific
 2290         information. By setting thread-local storage it can then be
 2291         accessed with
 2292         <functionlink id="GetThreadLocalStorage"></functionlink>.
 2293         <p/>
 2294         This function is called by the agent to set the value of the <jvmti/>
 2295         thread-local storage. <jvmti/> supplies to the agent a pointer-size
 2296         thread-local storage that can be used to record per-thread
 2297         information.
 2298       </description>
 2299       <origin>jvmpi</origin>
 2300       <capabilities>
 2301       </capabilities>
 2302       <parameters>
 2303         <param id="thread">
 2304           <jthread null="current" impl="noconvert"/>
 2305             <description>
 2306               Store to this thread.
 2307             </description>
 2308         </param>
 2309         <param id="data">
 2310           <inbuf>
 2311             <void/>
 2312             <nullok>value is set to <code>NULL</code></nullok>
 2313           </inbuf>
 2314           <description>
 2315             The value to be entered into the thread-local storage.
 2316           </description>
 2317         </param>
 2318       </parameters>
 2319       <errors>
 2320       </errors>
 2321     </function>
 2322 
 2323     <function id="GetThreadLocalStorage" jkernel="yes" impl="innative notrace" phase="start" num="102">
 2324       <synopsis>Get Thread Local Storage</synopsis>

 2391           <description>
 2392             The parent thread group.
 2393           </description>
 2394         </field>
 2395         <field id="name">
 2396           <allocfieldbuf><char/></allocfieldbuf>
 2397           <description>
 2398             The thread group's name, encoded as a
 2399             <internallink id="mUTF">modified UTF-8</internallink> string.
 2400           </description>
 2401         </field>
 2402         <field id="max_priority">
 2403           <jint/>
 2404           <description>
 2405             The maximum priority for this thread group.
 2406           </description>
 2407         </field>
 2408         <field id="is_daemon">
 2409           <jboolean/>
 2410           <description>
 2411             <code>JNI_FALSE</code>.
 2412             The concept of daemon thread group no longer exists.
 2413           </description>
 2414         </field>
 2415       </typedef>
 2416       <description>
 2417         Get information about the thread group. The fields of the
 2418         <functionlink id="jvmtiThreadGroupInfo"></functionlink> structure
 2419         are filled in with details of the specified thread group.
 2420       </description>
 2421       <origin>jvmdi</origin>
 2422       <capabilities>
 2423       </capabilities>
 2424       <parameters>
 2425         <param id="group">
 2426           <jthreadGroup/>
 2427           <description>
 2428             The thread group to query.
 2429           </description>
 2430         </param>
 2431         <param id="info_ptr">
 2432           <outptr><struct>jvmtiThreadGroupInfo</struct></outptr>
 2433           <description>
 2434             On return, filled with information describing the specified
 2435             thread group.
 2436           </description>
 2437         </param>
 2438       </parameters>
 2439       <errors>
 2440       </errors>
 2441     </function>
 2442 
 2443     <function id="GetThreadGroupChildren" num="15">
 2444       <synopsis>Get Thread Group Children</synopsis>
 2445       <description>
 2446         Get the live platform threads and the child thread groups in this
 2447         thread group.  Virtual threads are not considered live threads in
 2448         a thread group and not returned by this function.
 2449       </description>
 2450       <origin>jvmdi</origin>
 2451       <capabilities>
 2452       </capabilities>
 2453       <parameters>
 2454         <param id="group">
 2455           <jthreadGroup/>
 2456           <description>
 2457             The group to query.
 2458           </description>
 2459         </param>
 2460         <param id="thread_count_ptr">
 2461           <outptr><jint/></outptr>
 2462           <description>
 2463             On return, points to the number of live threads in this thread group.
 2464           </description>
 2465         </param>
 2466         <param id="threads_ptr">
 2467           <allocbuf outcount="thread_count_ptr"><jthread/></allocbuf>
 2468             <description>
 2469               On return, points to an array of the live threads in this thread group.
 2470             </description>
 2471         </param>
 2472         <param id="group_count_ptr">
 2473           <outptr><jint/></outptr>
 2474           <description>
 2475             On return, points to the number of child thread groups
 2476           </description>
 2477         </param>
 2478         <param id="groups_ptr">
 2479           <allocbuf outcount="group_count_ptr"><jthreadGroup/></allocbuf>
 2480             <description>
 2481               On return, points to an array of the child thread groups.
 2482             </description>
 2483         </param>
 2484       </parameters>
 2485       <errors>
 2486       </errors>
 2487     </function>
 2488   </category>
 2489 
 2490   <category id="stack" label="Stack Frame">
 2491     <intro>
 2492         These functions provide information about the stack of a thread.
 2493         Stack frames are referenced by depth.
 2494         The frame at depth zero is the current frame.
 2495         <p/>
 2496         Stack frames are as described in
 2497         <vmspec chapter="3.6"/>,
 2498         That is, they correspond to method
 2499         invocations (including native methods) but do not correspond to platform native or
 2500         VM internal frames.
 2501         <p/>

 2589       printf("Executing method: %s", methodName);
 2590    }
 2591 }
 2592         </example>
 2593         <todo>
 2594           check example code.
 2595         </todo>
 2596         <p/>
 2597         The <paramlink id="thread"></paramlink> need not be suspended
 2598         to call this function.
 2599         <p/>
 2600         The <functionlink id="GetLineNumberTable"></functionlink>
 2601         function can be used to map locations to line numbers. Note that
 2602         this mapping can be done lazily.
 2603       </description>
 2604       <origin>jvmpi</origin>
 2605       <capabilities>
 2606       </capabilities>
 2607       <parameters>
 2608         <param id="thread">
 2609           <jthread null="current" impl="noconvert"/>
 2610             <description>
 2611               Fetch the stack trace of this thread.
 2612             </description>
 2613         </param>
 2614         <param id="start_depth">
 2615           <jint/>
 2616           <description>
 2617             Begin retrieving frames at this depth.
 2618             If non-negative, count from the current frame,
 2619             the first frame retrieved is at depth <code>start_depth</code>.
 2620             For example, if zero, start from the current frame; if one, start from the
 2621             caller of the current frame; if two, start from the caller of the
 2622             caller of the current frame; and so on.
 2623             If negative, count from below the oldest frame,
 2624             the first frame retrieved is at depth <i>stackDepth</i><code> + start_depth</code>,
 2625             where <i>stackDepth</i> is the count of frames on the stack.
 2626             For example, if negative one, only the oldest frame is retrieved;
 2627             if negative two, start from the frame called by the oldest frame.
 2628           </description>
 2629         </param>

 2648             On return, points to the number of records filled in.
 2649             For non-negative <code>start_depth</code>, this will be
 2650             min(<code>max_frame_count</code>, <i>stackDepth</i><code> - start_depth</code>).
 2651             For negative <code>start_depth</code>, this will be
 2652             min(<code>max_frame_count</code>, <code>-start_depth</code>).
 2653           </description>
 2654         </param>
 2655       </parameters>
 2656       <errors>
 2657         <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
 2658           <paramlink id="start_depth"/> is positive and greater than or equal to <i>stackDepth</i>.
 2659           Or <paramlink id="start_depth"/> is negative and less than <i>-stackDepth</i>.
 2660         </error>
 2661       </errors>
 2662     </function>
 2663 
 2664 
 2665     <function id="GetAllStackTraces" num="100">
 2666       <synopsis>Get All Stack Traces</synopsis>
 2667       <description>
 2668         Get the stack traces of all live platform threads attached to the VM.
 2669         The list includes the stack traces of
 2670         <internallink id="RunAgentThread">agent threads</internallink>.
 2671         It does not include the stack traces of virtual threads.
 2672         <p/>
 2673         If <paramlink id="max_frame_count"/> is less than the depth of a stack,
 2674         the <paramlink id="max_frame_count"/> topmost frames are returned for that thread,
 2675         otherwise the entire stack is returned.
 2676         The topmost frames, those most recently invoked, are at the beginning of the returned buffer.
 2677         <p/>
 2678         All stacks are collected simultaneously, that is, no changes will occur to the
 2679         thread state or stacks between the sampling of one thread and the next.
 2680         The threads need not be suspended.
 2681 
 2682         <example>
 2683 jvmtiStackInfo *stack_info;
 2684 jint thread_count;
 2685 int ti;
 2686 jvmtiError err;
 2687 
 2688 err = (*jvmti)-&gt;GetAllStackTraces(jvmti, MAX_FRAMES, &amp;stack_info, &amp;thread_count);
 2689 if (err != JVMTI_ERROR_NONE) {
 2690    ...
 2691 }
 2692 for (ti = 0; ti &lt; thread_count; ++ti) {

 2876           The thread being used to call this function is not attached
 2877           to the virtual machine.  Calls must be made from attached threads.
 2878         </error>
 2879       </errors>
 2880     </function>
 2881     </elide>
 2882 
 2883     <function id="GetFrameCount" num="16">
 2884       <synopsis>Get Frame Count</synopsis>
 2885       <description>
 2886         Get the number of frames currently in the specified thread's call stack.
 2887         <p/>
 2888         If this function is called for a thread actively executing bytecodes (for example,
 2889         not the current thread and not suspended), the information returned is transient.
 2890       </description>
 2891       <origin>jvmdi</origin>
 2892       <capabilities>
 2893       </capabilities>
 2894       <parameters>
 2895         <param id="thread">
 2896           <jthread null="current" impl="noconvert"/>
 2897             <description>
 2898               The thread to query.
 2899             </description>
 2900         </param>
 2901         <param id="count_ptr">
 2902           <outptr><jint/></outptr>
 2903           <description>
 2904             On return, points to the number of frames in the call stack.
 2905           </description>
 2906         </param>
 2907       </parameters>
 2908       <errors>
 2909       </errors>
 2910     </function>
 2911 
 2912     <function id="PopFrame" num="80">
 2913       <synopsis>Pop Frame</synopsis>
 2914       <description>
 2915         Pop the current frame of <code>thread</code>'s stack.
 2916         Popping a frame takes you to the previous frame.

 2951         Finally blocks are not executed.
 2952         <p/>
 2953         Changes to global state are not addressed and thus remain changed.
 2954         <p/>
 2955         The specified thread must be suspended or must be the current thread.
 2956         <p/>
 2957         Both the called method and calling method must be non-native Java programming
 2958         language methods.
 2959         <p/>
 2960         No <jvmti/> events are generated by this function.
 2961       </description>
 2962       <origin>jvmdi</origin>
 2963       <capabilities>
 2964         <required id="can_pop_frame"></required>
 2965       </capabilities>
 2966       <parameters>
 2967         <param id="thread">
 2968           <jthread/>
 2969             <description>
 2970               The thread whose current frame is to be popped.
 2971               The <code>thread</code> may not be a virtual thread. Otherwise, the error code
 2972               <errorlink id="JVMTI_ERROR_INVALID_THREAD"></errorlink> will be returned.
 2973             </description>
 2974         </param>
 2975       </parameters>
 2976       <errors>
 2977         <error id="JVMTI_ERROR_OPAQUE_FRAME">
 2978           Called or calling method is a native method.
 2979           The implementation is unable to pop this frame.
 2980         </error>
 2981         <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
 2982           Thread was not suspended and was not the current thread.
 2983         </error>
 2984         <error id="JVMTI_ERROR_NO_MORE_FRAMES">
 2985           There are less than two stack frames on the call stack.
 2986         </error>
 2987         <error id="JVMTI_ERROR_INVALID_THREAD">
 2988           <paramlink id="thread"/> is a virtual thread.
 2989         </error>
 2990       </errors>
 2991     </function>
 2992 
 2993     <function id="GetFrameLocation" num="19">
 2994       <synopsis>Get Frame Location</synopsis>
 2995       <description>
 2996         <p/>
 2997         For a Java programming language frame, return the location of the instruction
 2998         currently executing.
 2999       </description>
 3000       <origin>jvmdiClone</origin>
 3001       <capabilities>
 3002       </capabilities>
 3003       <parameters>
 3004         <param id="thread">
 3005           <jthread null="current" frame="frame" impl="noconvert"/>
 3006           <description>
 3007             The thread of the frame to query.
 3008           </description>
 3009         </param>
 3010         <param id="depth">
 3011           <jframeID thread="thread"/>
 3012           <description>
 3013             The depth of the frame to query.
 3014           </description>
 3015         </param>
 3016         <param id="method_ptr">
 3017           <outptr><jmethodID/></outptr>
 3018             <description>
 3019               On return, points to the method for the current location.
 3020             </description>
 3021         </param>
 3022         <param id="location_ptr">
 3023           <outptr><jlocation/></outptr>
 3024           <description>
 3025             On return, points to the index of the currently

 3034     </function>
 3035 
 3036     <function id="NotifyFramePop" num="20">
 3037       <synopsis>Notify Frame Pop</synopsis>
 3038       <description>
 3039         When the frame that is currently at <paramlink id="depth"></paramlink>
 3040         is popped from the stack, generate a
 3041         <eventlink id="FramePop"></eventlink> event.  See the
 3042         <eventlink id="FramePop"></eventlink> event for details.
 3043         Only frames corresponding to non-native Java programming language
 3044         methods can receive notification.
 3045         <p/>
 3046         The specified thread must be suspended or must be the current thread.
 3047       </description>
 3048       <origin>jvmdi</origin>
 3049       <capabilities>
 3050         <required id="can_generate_frame_pop_events"></required>
 3051       </capabilities>
 3052       <parameters>
 3053         <param id="thread">
 3054           <jthread null="current" frame="depth" impl="noconvert"/>
 3055           <description>
 3056             The thread of the frame for which the frame pop event will be generated.
 3057           </description>
 3058         </param>
 3059         <param id="depth">
 3060           <jframeID thread="thread"/>
 3061           <description>
 3062             The depth of the frame for which the frame pop event will be generated.
 3063           </description>
 3064         </param>
 3065       </parameters>
 3066       <errors>
 3067         <error id="JVMTI_ERROR_OPAQUE_FRAME">
 3068           The frame at <code>depth</code> is executing a
 3069           native method.
 3070         </error>
 3071         <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
 3072           Thread was not suspended and was not the current thread.
 3073         </error>
 3074       </errors>
 3075     </function>
 3076 
 3077   </category>
 3078 
 3079   <category id="ForceEarlyReturn" label="Force Early Return">
 3080     <intro>
 3081       These functions allow an agent to force a method
 3082       to return at any point during its execution.
 3083       The method which will return early is referred to as the <i>called method</i>.
 3084       The called method is the current method
 3085       (as defined by
 3086       <vmspec chapter="3.6"/>)
 3087       for the specified thread at
 3088       the time the function is called.
 3089       <p/>
 3090       The <code>thread</code> may not be a virtual thread. Otherwise, the error code
 3091       <errorlink id="JVMTI_ERROR_INVALID_THREAD"></errorlink> will be returned.
 3092       The specified thread must be suspended or must be the current thread.
 3093       The return occurs when execution of Java programming
 3094       language code is resumed on this thread.
 3095       Between calling one of these functions and resumption
 3096       of thread execution, the state of the stack is undefined.
 3097       <p/>
 3098       No further instructions are executed in the called method.
 3099       Specifically, finally blocks are not executed.
 3100       Note: this can cause inconsistent states in the application.
 3101       <p/>
 3102       A lock acquired by calling the called method
 3103       (if it is a <code>synchronized</code>  method)
 3104       and locks acquired by entering <code>synchronized</code>
 3105       blocks within the called method are released.
 3106       Note: this does not apply to native locks or
 3107       <code>java.util.concurrent.locks</code> locks.
 3108       <p/>
 3109       Events, such as <eventlink id="MethodExit"></eventlink>,
 3110       are generated as they would be in a normal return.
 3111       <p/>

 3139             The return value for the called frame.
 3140             An object or <code>NULL</code>.
 3141           </description>
 3142         </param>
 3143       </parameters>
 3144       <errors>
 3145         <error id="JVMTI_ERROR_OPAQUE_FRAME">
 3146           Attempted to return early from a frame
 3147           corresponding to a native method.
 3148           Or the implementation is unable to provide
 3149           this functionality on this frame.
 3150         </error>
 3151         <error id="JVMTI_ERROR_TYPE_MISMATCH">
 3152           The result type of the called method is not
 3153           <code>Object</code> or a subclass of <code>Object</code>.
 3154         </error>
 3155         <error id="JVMTI_ERROR_TYPE_MISMATCH">
 3156           The supplied <paramlink id="value"/> is not compatible with the
 3157           result type of the called method.
 3158         </error>
 3159         <error id="JVMTI_ERROR_INVALID_THREAD">
 3160           <paramlink id="thread"/> is a virtual thread.
 3161         </error>
 3162         <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
 3163           Thread was not suspended and was not the current thread.
 3164         </error>
 3165         <error id="JVMTI_ERROR_NO_MORE_FRAMES">
 3166           There are no more frames on the call stack.
 3167         </error>
 3168       </errors>
 3169     </function>
 3170 
 3171     <function id="ForceEarlyReturnInt" num="82" since="1.1">
 3172       <synopsis>Force Early Return - Int</synopsis>
 3173       <description>
 3174         This function can be used to return from a method whose
 3175         result type is <code>int</code>, <code>short</code>,
 3176         <code>char</code>, <code>byte</code>, or
 3177         <code>boolean</code>.
 3178       </description>
 3179       <origin>new</origin>
 3180       <capabilities>
 3181         <required id="can_force_early_return"></required>

 3190         <param id="value">
 3191           <jint/>
 3192           <description>
 3193             The return value for the called frame.
 3194           </description>
 3195         </param>
 3196       </parameters>
 3197       <errors>
 3198         <error id="JVMTI_ERROR_OPAQUE_FRAME">
 3199           Attempted to return early from a frame
 3200           corresponding to a native method.
 3201           Or the implementation is unable to provide
 3202           this functionality on this frame.
 3203         </error>
 3204         <error id="JVMTI_ERROR_TYPE_MISMATCH">
 3205           The result type of the called method is not
 3206           <code>int</code>, <code>short</code>,
 3207           <code>char</code>, <code>byte</code>, or
 3208           <code>boolean</code>.
 3209         </error>
 3210         <error id="JVMTI_ERROR_INVALID_THREAD">
 3211           <paramlink id="thread"/> is a virtual thread.
 3212         </error>
 3213         <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
 3214           Thread was not suspended and was not the current thread.
 3215         </error>
 3216         <error id="JVMTI_ERROR_NO_MORE_FRAMES">
 3217           There are no frames on the call stack.
 3218         </error>
 3219       </errors>
 3220     </function>
 3221 
 3222     <function id="ForceEarlyReturnLong" num="83" since="1.1">
 3223       <synopsis>Force Early Return - Long</synopsis>
 3224       <description>
 3225         This function can be used to return from a method whose
 3226         result type is <code>long</code>.
 3227       </description>
 3228       <origin>new</origin>
 3229       <capabilities>
 3230         <required id="can_force_early_return"></required>
 3231       </capabilities>
 3232       <parameters>

 3236             The thread whose current frame is to return early.
 3237           </description>
 3238         </param>
 3239         <param id="value">
 3240           <jlong/>
 3241           <description>
 3242             The return value for the called frame.
 3243           </description>
 3244         </param>
 3245       </parameters>
 3246       <errors>
 3247         <error id="JVMTI_ERROR_OPAQUE_FRAME">
 3248           Attempted to return early from a frame
 3249           corresponding to a native method.
 3250           Or the implementation is unable to provide
 3251           this functionality on this frame.
 3252         </error>
 3253         <error id="JVMTI_ERROR_TYPE_MISMATCH">
 3254           The result type of the called method is not <code>long</code>.
 3255         </error>
 3256         <error id="JVMTI_ERROR_INVALID_THREAD">
 3257           <paramlink id="thread"/> is a virtual thread.
 3258         </error>
 3259         <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
 3260           Thread was not suspended and was not the current thread.
 3261         </error>
 3262         <error id="JVMTI_ERROR_NO_MORE_FRAMES">
 3263           There are no frames on the call stack.
 3264         </error>
 3265       </errors>
 3266     </function>
 3267 
 3268     <function id="ForceEarlyReturnFloat" num="84" since="1.1">
 3269       <synopsis>Force Early Return - Float</synopsis>
 3270       <description>
 3271         This function can be used to return from a method whose
 3272         result type is <code>float</code>.
 3273       </description>
 3274       <origin>new</origin>
 3275       <capabilities>
 3276         <required id="can_force_early_return"></required>
 3277       </capabilities>
 3278       <parameters>

 3282             The thread whose current frame is to return early.
 3283           </description>
 3284         </param>
 3285         <param id="value">
 3286           <jfloat/>
 3287           <description>
 3288             The return value for the called frame.
 3289           </description>
 3290         </param>
 3291       </parameters>
 3292       <errors>
 3293         <error id="JVMTI_ERROR_OPAQUE_FRAME">
 3294           Attempted to return early from a frame
 3295           corresponding to a native method.
 3296           Or the implementation is unable to provide
 3297           this functionality on this frame.
 3298         </error>
 3299         <error id="JVMTI_ERROR_TYPE_MISMATCH">
 3300           The result type of the called method is not <code>float</code>.
 3301         </error>
 3302         <error id="JVMTI_ERROR_INVALID_THREAD">
 3303           <paramlink id="thread"/> is a virtual thread.
 3304         </error>
 3305         <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
 3306           Thread was not suspended and was not the current thread.
 3307         </error>
 3308         <error id="JVMTI_ERROR_NO_MORE_FRAMES">
 3309           There are no frames on the call stack.
 3310         </error>
 3311       </errors>
 3312     </function>
 3313 
 3314     <function id="ForceEarlyReturnDouble" num="85" since="1.1">
 3315       <synopsis>Force Early Return - Double</synopsis>
 3316       <description>
 3317         This function can be used to return from a method whose
 3318         result type is <code>double</code>.
 3319       </description>
 3320       <origin>new</origin>
 3321       <capabilities>
 3322         <required id="can_force_early_return"></required>
 3323       </capabilities>
 3324       <parameters>

 3326           <jthread null="current"/>
 3327           <description>
 3328             The thread whose current frame is to return early.
 3329           </description>
 3330         </param>
 3331         <param id="value">
 3332           <jdouble/>
 3333           <description>
 3334             The return value for the called frame.
 3335           </description>
 3336         </param>
 3337       </parameters>
 3338       <errors>
 3339         <error id="JVMTI_ERROR_OPAQUE_FRAME">
 3340           Attempted to return early from a frame corresponding to a native method.
 3341           Or the implementation is unable to provide this functionality on this frame.
 3342         </error>
 3343         <error id="JVMTI_ERROR_TYPE_MISMATCH">
 3344           The result type of the called method is not <code>double</code>.
 3345         </error>
 3346         <error id="JVMTI_ERROR_INVALID_THREAD">
 3347           <paramlink id="thread"/> is a virtual thread.
 3348         </error>
 3349         <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
 3350           Thread was not suspended and was not the current thread.
 3351         </error>
 3352         <error id="JVMTI_ERROR_NO_MORE_FRAMES">
 3353           There are no frames on the call stack.
 3354         </error>
 3355       </errors>
 3356     </function>
 3357 
 3358     <function id="ForceEarlyReturnVoid" num="86" since="1.1">
 3359       <synopsis>Force Early Return - Void</synopsis>
 3360       <description>
 3361         This function can be used to return from a method with no result type.
 3362         That is, the called method must be declared <code>void</code>.
 3363       </description>
 3364       <origin>new</origin>
 3365       <capabilities>
 3366         <required id="can_force_early_return"></required>
 3367       </capabilities>
 3368       <parameters>
 3369         <param id="thread">
 3370           <jthread null="current"/>
 3371           <description>
 3372             The thread whose current frame is to return early.
 3373           </description>
 3374         </param>
 3375       </parameters>
 3376       <errors>
 3377         <error id="JVMTI_ERROR_OPAQUE_FRAME">
 3378           Attempted to return early from a frame
 3379           corresponding to a native method.
 3380           Or the implementation is unable to provide
 3381           this functionality on this frame.
 3382         </error>
 3383         <error id="JVMTI_ERROR_TYPE_MISMATCH">
 3384           The called method has a result type.
 3385         </error>
 3386         <error id="JVMTI_ERROR_INVALID_THREAD">
 3387           <paramlink id="thread"/> is a virtual thread.
 3388         </error>
 3389         <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
 3390           Thread was not suspended and was not the current thread.
 3391         </error>
 3392         <error id="JVMTI_ERROR_NO_MORE_FRAMES">
 3393           There are no frames on the call stack.
 3394         </error>
 3395       </errors>
 3396     </function>
 3397 
 3398   </category>
 3399 
 3400   <category id="Heap" label="Heap">
 3401     <intro>
 3402       These functions are used to analyze the heap.
 3403       Functionality includes the ability to view the objects in the
 3404       heap and to tag these objects.
 3405     </intro>
 3406 
 3407     <intro id="objectTags" label="Object Tags">
 3408       A <i>tag</i> is a value associated with an object.

 5829       These functions are used to retrieve or set the value of a local variable.
 5830       The variable is identified by the depth of the frame containing its
 5831       value and the variable's slot number within that frame.
 5832       The mapping of variables to
 5833       slot numbers can be obtained with the function
 5834       <functionlink id="GetLocalVariableTable"></functionlink>.
 5835     </intro>
 5836 
 5837     <function id="GetLocalObject" num="21">
 5838       <synopsis>Get Local Variable - Object</synopsis>
 5839       <description>
 5840         This function can be used to retrieve the value of a local
 5841         variable whose type is <code>Object</code> or a subclass of <code>Object</code>.
 5842       </description>
 5843       <origin>jvmdi</origin>
 5844       <capabilities>
 5845         <required id="can_access_local_variables"></required>
 5846       </capabilities>
 5847       <parameters>
 5848         <param id="thread">
 5849           <jthread null="current" frame="frame" impl="noconvert"/>
 5850           <description>
 5851             The thread of the frame containing the variable's value.
 5852           </description>
 5853         </param>
 5854         <param id="depth">
 5855           <jframeID thread="thread"/>
 5856           <description>
 5857             The depth of the frame containing the variable's value.
 5858           </description>
 5859         </param>
 5860         <param id="slot">
 5861           <jint/>
 5862           <description>
 5863             The variable's slot number.
 5864           </description>
 5865         </param>
 5866         <param id="value_ptr">
 5867           <outptr><jobject/></outptr>
 5868             <description>
 5869               On return, points to the variable's value.

 5882           Not a visible frame
 5883         </error>
 5884       </errors>
 5885     </function>
 5886 
 5887     <function id="GetLocalInstance" num="155" since="1.2">
 5888       <synopsis>Get Local Instance</synopsis>
 5889       <description>
 5890         This function can be used to retrieve the value of the local object
 5891         variable at slot 0 (the "<code>this</code>" object) from non-static
 5892         frames.  This function can retrieve the "<code>this</code>" object from
 5893         native method frames, whereas <code>GetLocalObject()</code> would
 5894         return <code>JVMTI_ERROR_OPAQUE_FRAME</code> in those cases.
 5895       </description>
 5896       <origin>new</origin>
 5897       <capabilities>
 5898         <required id="can_access_local_variables"></required>
 5899       </capabilities>
 5900       <parameters>
 5901         <param id="thread">
 5902           <jthread null="current" frame="frame" impl="noconvert"/>
 5903           <description>
 5904             The thread of the frame containing the variable's value.
 5905           </description>
 5906         </param>
 5907         <param id="depth">
 5908           <jframeID thread="thread"/>
 5909           <description>
 5910             The depth of the frame containing the variable's value.
 5911           </description>
 5912         </param>
 5913         <param id="value_ptr">
 5914           <outptr><jobject/></outptr>
 5915             <description>
 5916               On return, points to the variable's value.
 5917             </description>
 5918         </param>
 5919       </parameters>
 5920       <errors>
 5921         <error id="JVMTI_ERROR_INVALID_SLOT">
 5922           If the specified frame is a static method frame.
 5923         </error>
 5924       </errors>
 5925     </function>
 5926     <function id="GetLocalInt" num="22">
 5927       <synopsis>Get Local Variable - Int</synopsis>
 5928       <description>
 5929         This function can be used to retrieve the value of a local
 5930         variable whose type is <code>int</code>,
 5931         <code>short</code>, <code>char</code>, <code>byte</code>, or
 5932         <code>boolean</code>.
 5933       </description>
 5934       <origin>jvmdi</origin>
 5935       <capabilities>
 5936         <required id="can_access_local_variables"></required>
 5937       </capabilities>
 5938       <parameters>
 5939         <param id="thread">
 5940           <jthread null="current" frame="frame" impl="noconvert"/>
 5941           <description>
 5942             The thread of the frame containing the variable's value.
 5943           </description>
 5944         </param>
 5945         <param id="depth">
 5946           <jframeID thread="thread"/>
 5947           <description>
 5948             The depth of the frame containing the variable's value.
 5949           </description>
 5950         </param>
 5951         <param id="slot">
 5952           <jint/>
 5953           <description>
 5954             The variable's slot number.
 5955           </description>
 5956         </param>
 5957         <param id="value_ptr">
 5958           <outptr><jint/></outptr>
 5959           <description>
 5960             On return, points to the variable's value.

 5972           <code>boolean</code>.
 5973         </error>
 5974         <error id="JVMTI_ERROR_OPAQUE_FRAME">
 5975           Not a visible frame
 5976         </error>
 5977       </errors>
 5978     </function>
 5979 
 5980     <function id="GetLocalLong" num="23">
 5981       <synopsis>Get Local Variable - Long</synopsis>
 5982       <description>
 5983         This function can be used to retrieve the value of a local
 5984         variable whose type is <code>long</code>.
 5985       </description>
 5986       <origin>jvmdi</origin>
 5987       <capabilities>
 5988         <required id="can_access_local_variables"></required>
 5989       </capabilities>
 5990       <parameters>
 5991         <param id="thread">
 5992           <jthread null="current" frame="frame" impl="noconvert"/>
 5993           <description>
 5994             The thread of the frame containing the variable's value.
 5995           </description>
 5996         </param>
 5997         <param id="depth">
 5998           <jframeID thread="thread"/>
 5999           <description>
 6000             The depth of the frame containing the variable's value.
 6001           </description>
 6002         </param>
 6003         <param id="slot">
 6004           <jint/>
 6005           <description>
 6006             The variable's slot number.
 6007           </description>
 6008         </param>
 6009         <param id="value_ptr">
 6010           <outptr><jlong/></outptr>
 6011           <description>
 6012             On return, points to the variable's value.

 6021           The variable type is not <code>long</code>.
 6022         </error>
 6023         <error id="JVMTI_ERROR_OPAQUE_FRAME">
 6024           Not a visible frame
 6025         </error>
 6026       </errors>
 6027     </function>
 6028 
 6029     <function id="GetLocalFloat" num="24">
 6030       <synopsis>Get Local Variable - Float</synopsis>
 6031       <description>
 6032         This function can be used to retrieve the value of a local
 6033         variable whose type is <code>float</code>.
 6034       </description>
 6035       <origin>jvmdi</origin>
 6036       <capabilities>
 6037         <required id="can_access_local_variables"></required>
 6038       </capabilities>
 6039       <parameters>
 6040         <param id="thread">
 6041           <jthread null="current" frame="frame" impl="noconvert"/>
 6042           <description>
 6043             The thread of the frame containing the variable's value.
 6044           </description>
 6045         </param>
 6046         <param id="depth">
 6047           <jframeID thread="thread"/>
 6048           <description>
 6049             The depth of the frame containing the variable's value.
 6050           </description>
 6051         </param>
 6052         <param id="slot">
 6053           <jint/>
 6054           <description>
 6055             The variable's slot number.
 6056           </description>
 6057         </param>
 6058         <param id="value_ptr">
 6059           <outptr><jfloat/></outptr>
 6060           <description>
 6061             On return, points to the variable's value.

 6070           The variable type is not <code>float</code>.
 6071         </error>
 6072         <error id="JVMTI_ERROR_OPAQUE_FRAME">
 6073           Not a visible frame
 6074         </error>
 6075       </errors>
 6076     </function>
 6077 
 6078     <function id="GetLocalDouble" num="25">
 6079       <synopsis>Get Local Variable - Double</synopsis>
 6080       <description>
 6081         This function can be used to retrieve the value of a local
 6082         variable whose type is <code>long</code>.
 6083       </description>
 6084       <origin>jvmdi</origin>
 6085       <capabilities>
 6086         <required id="can_access_local_variables"></required>
 6087       </capabilities>
 6088       <parameters>
 6089         <param id="thread">
 6090           <jthread null="current" frame="frame" impl="noconvert"/>
 6091           <description>
 6092             The thread of the frame containing the variable's value.
 6093           </description>
 6094         </param>
 6095         <param id="depth">
 6096           <jframeID thread="thread"/>
 6097           <description>
 6098             The depth of the frame containing the variable's value.
 6099           </description>
 6100         </param>
 6101         <param id="slot">
 6102           <jint/>
 6103           <description>
 6104             The variable's slot number.
 6105           </description>
 6106         </param>
 6107         <param id="value_ptr">
 6108           <outptr><jdouble/></outptr>
 6109           <description>
 6110             On return, points to the variable's value.

10560       </capabilityfield>
10561       <capabilityfield id="can_generate_early_class_hook_events" since="9">
10562         <description>
10563           Can generate the <eventlink id="ClassFileLoadHook"/> events
10564           in the primordial phase. If this capability and
10565           <internallink id="jvmtiCapabilities.can_generate_all_class_hook_events">
10566           <code>can_generate_all_class_hook_events</code></internallink>
10567           are enabled then the <eventlink id="ClassFileLoadHook"/> events
10568           can be posted for classes loaded in the primordial phase.
10569           See <eventlink id="ClassFileLoadHook"/>.
10570         </description>
10571       </capabilityfield>
10572       <capabilityfield id="can_generate_sampled_object_alloc_events" since="11">
10573         <description>
10574           Can generate sampled allocation events.
10575           If this capability is enabled then the heap sampling method
10576           <functionlink id="SetHeapSamplingInterval"></functionlink> can be
10577           called and <eventlink id="SampledObjectAlloc"></eventlink> events can be generated.
10578         </description>
10579       </capabilityfield>
10580       <capabilityfield id="can_support_virtual_threads" since="14">
10581         <description>
10582           <b> can_support_virtual_threads is a preview API of the Java platform. </b>
10583           <i>Preview features may be removed in a future release, or upgraded to
10584           permanent features of the Java platform.</i>.
10585           <p/>
10586           Can support virtual threads.
10587           If this capability is enabled then the following functions can be called:
10588           <functionlink id="SuspendAllVirtualThreads"></functionlink>, 
10589           <functionlink id="ResumeAllVirtualThreads"></functionlink>,
10590           and the following events can be enabled:
10591           <eventlink id="VirtualThreadStart"></eventlink>,
10592           <eventlink id="VirtualThreadEnd"></eventlink>,
10593         </description>
10594       </capabilityfield>
10595     </capabilitiestypedef>
10596 
10597     <function id="GetPotentialCapabilities" jkernel="yes" phase="onload" num="140">
10598       <synopsis>Get Potential Capabilities</synopsis>
10599       <description>
10600         Returns via <paramlink id="capabilities_ptr"></paramlink> the <jvmti/>
10601         features that can potentially be possessed by this environment
10602         at this time.
10603         The returned capabilities differ from the complete set of capabilities
10604         implemented by the VM in two cases: another environment possesses
10605         capabilities that can only be possessed by one environment, or the
10606         current <functionlink id="GetPhase">phase</functionlink> is live,
10607         and certain capabilities can only be added during the <code>OnLoad</code> phase.
10608         The <functionlink id="AddCapabilities"></functionlink> function
10609         may be used to set any or all or these capabilities.
10610         Currently possessed capabilities are included.
10611         <p/>
10612         Typically this function is used in the <code>OnLoad</code> function.
10613         Some virtual machines may allow a limited set of capabilities to be
10614         added in the live phase.

10932         </param>
10933       </parameters>
10934       <errors>
10935       </errors>
10936     </function>
10937 
10938     <function id="GetCurrentThreadCpuTime" callbacksafe="safe" impl="innative notrace" phase="start" num="135">
10939       <synopsis>Get Current Thread CPU Time</synopsis>
10940       <description>
10941             Return the CPU time utilized by the current thread.
10942             <p/>
10943             Note that the <functionlink id="GetThreadCpuTime"/>
10944             function provides CPU time for any thread, including
10945             the current thread. <code>GetCurrentThreadCpuTime</code>
10946             exists to support platforms which cannot
10947             supply CPU time for threads other than the current
10948             thread or which have more accurate information for
10949             the current thread (see
10950             <functionlink id="GetCurrentThreadCpuTimerInfo"/> vs
10951             <functionlink id="GetThreadCpuTimerInfo"/>).
10952             The current thread may not be a virtual thread. Otherwise, the error code
10953             <errorlink id="JVMTI_ERROR_INVALID_THREAD"></errorlink> will be returned.
10954             On many platforms this call will be equivalent to:
10955 <example>
10956   GetThreadCpuTime(env, NULL, nanos_ptr)
10957 </example>
10958       </description>
10959       <origin>new</origin>
10960       <capabilities>
10961         <required id="can_get_current_thread_cpu_time">
10962             Can get current thread CPU time.
10963             <p/>
10964             If this capability is enabled after threads have started,
10965             the implementation may choose any time up
10966             to and including the time that the capability is enabled
10967             as the point where CPU time collection starts.
10968             <p/>
10969             This capability must be potentially available on any
10970             platform where
10971             <internallink id="jvmtiCapabilities.can_get_thread_cpu_time"><code>can_get_thread_cpu_time</code></internallink>
10972             is potentially available.
10973         </required>
10974       </capabilities>
10975       <parameters>
10976         <param id="nanos_ptr">
10977           <outptr><jlong/></outptr>
10978           <description>
10979             On return, points to the CPU time used by this thread
10980             in nanoseconds.
10981             This is an unsigned value.  If tested or printed as a jlong (signed value)
10982             it may appear to be a negative number.
10983           </description>
10984         </param>
10985       </parameters>
10986       <errors>
10987         <error id="JVMTI_ERROR_INVALID_THREAD">
10988           Current thread is a virtual thread.
10989         </error>
10990       </errors>
10991     </function>
10992 
10993     <function id="GetThreadCpuTimerInfo" num="136">
10994       <synopsis>Get Thread CPU Timer Information</synopsis>
10995       <description>
10996         Get information about the
10997         <functionlink id="GetThreadCpuTime"/> timer.
10998         The fields of the <datalink id="jvmtiTimerInfo"/> structure
10999         are filled in with details about the timer.
11000         This information is specific to the platform and the implementation of
11001         <functionlink id="GetThreadCpuTime"/> and thus
11002         does not vary by thread nor does it vary
11003         during a particular invocation of the VM.
11004         <p/>
11005         Note that the implementations of <functionlink id="GetCurrentThreadCpuTime"/>
11006         and <functionlink id="GetThreadCpuTime"/> may differ, and thus the values
11007         returned by <functionlink id="GetCurrentThreadCpuTimerInfo"/>
11008         and <code>GetThreadCpuTimerInfo</code>
11009         may differ -- see <functionlink id="GetCurrentThreadCpuTime"/> for more information.

11034           <p/>
11035           Get information about this timer with
11036           <functionlink id="GetThreadCpuTimerInfo"/>.
11037       </description>
11038       <origin>new</origin>
11039       <capabilities>
11040         <required id="can_get_thread_cpu_time">
11041             Can get thread CPU time.
11042             <p/>
11043             If this capability is enabled after threads have started,
11044             the implementation may choose any time up
11045             to and including the time that the capability is enabled
11046             as the point where CPU time collection starts.
11047         </required>
11048       </capabilities>
11049       <parameters>
11050         <param id="thread">
11051           <jthread null="current"/>
11052             <description>
11053               The thread to query.
11054               The <code>thread</code> may not be a virtual thread. Otherwise, the error code
11055                <errorlink id="JVMTI_ERROR_INVALID_THREAD"></errorlink> will be returned.
11056              </description>
11057         </param>
11058         <param id="nanos_ptr">
11059           <outptr><jlong/></outptr>
11060           <description>
11061             On return, points to the CPU time used by the specified thread
11062             in nanoseconds.
11063             This is an unsigned value.  If tested or printed as a jlong (signed value)
11064             it may appear to be a negative number.
11065           </description>
11066         </param>
11067       </parameters>
11068       <errors>
11069         <error id="JVMTI_ERROR_INVALID_THREAD">
11070           <paramlink id="thread"/> is a virtual thread.
11071         </error>
11072       </errors>
11073     </function>
11074 
11075     <function id="GetTimerInfo" phase="any" callbacksafe="safe" num="138">
11076       <synopsis>Get Timer Information</synopsis>
11077       <description>
11078         Get information about the
11079         <functionlink id="GetTime"/> timer.
11080         The fields of the <datalink id="jvmtiTimerInfo"/> structure
11081         are filled in with details about the timer.
11082         This information will not change during a particular invocation of the VM.
11083       </description>
11084       <origin>new</origin>
11085       <capabilities>
11086       </capabilities>
11087       <parameters>
11088         <param id="info_ptr">
11089           <outptr><struct>jvmtiTimerInfo</struct></outptr>
11090           <description>
11091             On return, filled with information describing the time

12849           </description>
12850       </param>
12851       <param id="location">
12852         <jlocation/>
12853         <description>
12854           Location where exception is being caught
12855         </description>
12856       </param>
12857       <param id="exception">
12858         <jobject/>
12859           <description>
12860             Exception being caught
12861           </description>
12862       </param>
12863     </parameters>
12864   </event>
12865 
12866   <event label="Thread Start"
12867          id="ThreadStart" const="JVMTI_EVENT_THREAD_START" num="52" phase="start">
12868     <description>
12869       A thread start event is generated by a new thread before its initial
12870       method executes. Thread start events are generated by platform threads.
12871       The capability
12872       <internallink id="jvmtiCapabilities.can_support_virtual_threads">
12873       <code>can_support_virtual_threads</code></internallink> determines
12874       if a new virtual thread generates a <code>ThreadStart</code> event or
12875       a <eventlink id="VirtualThreadStart"/> event. If disabled, a virtual
12876       thread generates a <code>ThreadStart</code> event. If enabled, a virtual
12877       thread generates a <code>VirtualThreadStart</code> event.
12878       <p/>
12879       A thread may be listed in the array returned by
12880       <functionlink id="GetAllThreads"></functionlink>
12881       before its thread start event is generated.
12882       It is possible for other events to be generated
12883       on a thread before its thread start event.
12884       <p/>
12885       The event is sent on the newly started <paramlink id="thread"></paramlink>.
12886     </description>
12887     <origin>jvmdi</origin>
12888     <capabilities>
12889     </capabilities>
12890     <parameters>
12891       <param id="jni_env">
12892         <outptr>
12893           <struct>JNIEnv</struct>
12894         </outptr>
12895           <description>
12896             The JNI environment of the event (current) thread.
12897           </description>
12898       </param>
12899       <param id="thread">
12900         <jthread/>
12901           <description>
12902             Thread starting
12903           </description>
12904       </param>
12905     </parameters>
12906   </event>
12907 
12908   <event label="Thread End"
12909          id="ThreadEnd" const="JVMTI_EVENT_THREAD_END" filtered="thread" num="53" phase="start">
12910     <description>
12911       A thread end event is generated by a terminating thread after its
12912       initial method has finished execution.
12913       Thread end events are generated by platform threads.
12914       The capability
12915       <internallink id="jvmtiCapabilities.can_support_virtual_threads">
12916       <code>can_support_virtual_threads</code></internallink> determines
12917       if a terminating virtual thread generates a <code>ThreadEnd</code>
12918       event or a <eventlink id="VirtualThreadEnd"/> event. If disabled, a
12919       virtual thread generates a <code>ThreadEnd</code> event. If enabled,
12920       a virtual thread generates a <code>VirtualThreadEnd</code> event.
12921       <p/>
12922       A thread may be listed in the array returned by
12923       <functionlink id="GetAllThreads"></functionlink>
12924       after its thread end event is generated.
12925       No events are generated on a thread
12926       after its thread end event.
12927       <p/>
12928       The event is sent on the dying <paramlink id="thread"></paramlink>.
12929     </description>
12930     <origin>jvmdi</origin>
12931     <capabilities>
12932     </capabilities>
12933     <parameters>
12934       <param id="jni_env">
12935         <outptr>
12936           <struct>JNIEnv</struct>
12937         </outptr>
12938           <description>
12939             The JNI environment of the event (current) thread.
12940           </description>
12941       </param>
12942       <param id="thread">
12943         <jthread/>
12944           <description>
12945             Thread ending
12946           </description>
12947       </param>
12948     </parameters>
12949   </event>
12950 
12951  <event label="Virtual Thread Start"
12952          id="VirtualThreadStart" const="JVMTI_EVENT_VIRTUAL_THREAD_START" filtered="thread" num="87" phase="start" since="14">
12953     <description>
12954       <b> VirtualThreadStart is a preview API of the Java platform. </b>
12955       <i>Preview features may be removed in a future release, or upgraded to
12956       permanent features of the Java platform.</i>.
12957       <p/>
12958       Virtual thread started events are generated before its initial method executes.
12959       <p/>
12960       The event is sent on the <paramlink id="thread"></paramlink>.
12961     </description>
12962     <origin>new</origin>
12963     <capabilities>
12964       <required id="can_support_virtual_threads">Can support virtual threads</required>
12965     </capabilities>
12966     <parameters>
12967       <param id="jni_env">
12968         <outptr>
12969           <struct>JNIEnv</struct>
12970         </outptr>
12971           <description>
12972             The JNI environment of the event (current) thread.
12973           </description>
12974       </param>
12975       <param id="virtual_thread">
12976         <jthread/>
12977           <description>
12978             Virtual thread started for execution.
12979           </description>
12980       </param>
12981     </parameters>
12982   </event>
12983 
12984   <event label="Virtual Thread End"
12985          id="VirtualThreadEnd" const="JVMTI_EVENT_VIRTUAL_THREAD_END" filtered="thread" num="88" phase="start" since="14">
12986     <description>
12987       <b> VirtualThreadEnd is a preview API of the Java platform. </b>
12988       <i>Preview features may be removed in a future release, or upgraded to
12989       permanent features of the Java platform.</i>.
12990       <p/>
12991       Virtual thread end events are generated after its initial method has finished execution.
12992       <p/>
12993       The event is sent on the <paramlink id="thread"></paramlink>.
12994     </description>
12995     <origin>new</origin>
12996     <capabilities>
12997       <required id="can_support_virtual_threads">Can support virtual threads</required>
12998     </capabilities>
12999     <parameters>
13000       <param id="jni_env">
13001         <outptr>
13002           <struct>JNIEnv</struct>
13003         </outptr>
13004           <description>
13005             The JNI environment of the event (current) thread.
13006           </description>
13007       </param>
13008       <param id="virtual_thread">
13009         <jthread/>
13010           <description>
13011             Virtual thread being ended.
13012           </description>
13013       </param>
13014     </parameters>
13015   </event>
13016 
13017   <elide>
13018   <event label="Virtual Thread Mount"
13019          id="VirtualThreadMount" const="JVMTI_EVENT_VIRTUAL_THREAD_MOUNT" filtered="thread" num="89" phase="start" since="14">
13020     <description>
13021       Virtual thread mount events are generated before its method continue to execute on the mounted thread.
13022       <p/>
13023       The event is sent on the <paramlink id="thread"></paramlink> the virtual thread is mounted to.
13024     </description>
13025     <origin>new</origin>
13026     <capabilities>
13027       <required id="can_support_virtual_threads">Can support virtual threads</required>
13028     </capabilities>
13029     <parameters>
13030       <param id="jni_env">
13031         <outptr>
13032           <struct>JNIEnv</struct>
13033         </outptr>
13034           <description>
13035             The JNI environment of the event (current) thread.
13036           </description>
13037       </param>
13038       <param id="virtual_thread">
13039         <jthread/>
13040           <description>
13041             Virtual thread that is mounted.
13042           </description>
13043       </param>
13044     </parameters>
13045   </event>
13046   </elide>
13047 
13048   <elide>
13049   <event label="Virtual Thread Unmount"
13050          id="VirtualThreadUnmount" const="JVMTI_EVENT_VIRTUAL_THREAD_UNMOUNT" filtered="thread" num="90" phase="start" since="14">
13051     <description>
13052       Virtual thread unmount events are generated when the virtual thread is about to be unmounted from the carrier thread.
13053       <p/>
13054       The event is sent on the <paramlink id="thread"></paramlink> the virtual thread is unmounted from.
13055     </description>
13056     <origin>new</origin>
13057     <capabilities>
13058       <required id="can_support_virtual_threads">Can support virtual threads</required>
13059     </capabilities>
13060     <parameters>
13061       <param id="jni_env">
13062         <outptr>
13063           <struct>JNIEnv</struct>
13064         </outptr>
13065           <description>
13066             The JNI environment of the event (current) thread.
13067           </description>
13068       </param>
13069       <param id="virtual_thread">
13070         <jthread/>
13071           <description>
13072             Virtual thread that is unmounted.
13073           </description>
13074       </param>
13075     </parameters>
13076   </event>
13077   </elide>
13078 
13079   <event label="Class Load"
13080          id="ClassLoad" const="JVMTI_EVENT_CLASS_LOAD" filtered="thread" phase="start" num="55">
13081     <description>
13082       A class load event is generated
13083       <functionlink id="GetLoadedClasses">when a class or interface is created.</functionlink>.
13084       <p/>
13085       Array class creation does not generate a class load event.
13086       The creation of a primitive class (for example, java.lang.Integer.TYPE)
13087       does not generate a class load event.
13088       <p/>
13089       The order of class load events generated by a particular thread is guaranteed
13090       to match the order of class loading within that thread.
13091       <p/>
13092       This event is sent at an early stage in loading the class. As
13093       a result the class should be used carefully.  Note, for example,
13094       that methods and fields are not yet loaded, so queries for methods,
13095       fields, subclasses, and so on will not give correct results.
13096       See "Loading of Classes and Interfaces" in the <i>Java Language
13097       Specification</i>.  For most
13098       purposes the <eventlink id="ClassPrepare"></eventlink> event will
< prev index next >