1 <?xml version="1.0" encoding="UTF-8"?>
2 <?xml-stylesheet type="text/xsl" href="jvmti.xsl"?>
3 <!--
4 Copyright (c) 2002, 2025, Oracle and/or its affiliates. All rights reserved.
5 DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
6
7 This code is free software; you can redistribute it and/or modify it
8 under the terms of the GNU General Public License version 2 only, as
9 published by the Free Software Foundation.
10
11 This code is distributed in the hope that it will be useful, but WITHOUT
12 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 version 2 for more details (a copy is included in the LICENSE file that
15 accompanied this code).
16
17 You should have received a copy of the GNU General Public License version
18 2 along with this work; if not, write to the Free Software Foundation,
19 Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20
21 Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 or visit www.oracle.com if you need additional information or have any
23 questions.
24 -->
5871 <description>
5872 The thread of the frame containing the variable's value.
5873 </description>
5874 </param>
5875 <param id="depth">
5876 <jframeID thread="thread"/>
5877 <description>
5878 The depth of the frame containing the variable's value.
5879 </description>
5880 </param>
5881 <param id="slot">
5882 <jint/>
5883 <description>
5884 The variable's slot number.
5885 </description>
5886 </param>
5887 <param id="value_ptr">
5888 <outptr><jobject/></outptr>
5889 <description>
5890 On return, points to the variable's value.
5891 </description>
5892 </param>
5893 </parameters>
5894 <errors>
5895 <error id="JVMTI_ERROR_INVALID_SLOT">
5896 Invalid <code>slot</code>.
5897 </error>
5898 <error id="JVMTI_ERROR_TYPE_MISMATCH">
5899 The variable type is not
5900 <code>Object</code> or a subclass of <code>Object</code>.
5901 </error>
5902 <error id="JVMTI_ERROR_OPAQUE_FRAME">
5903 The implementation is unable to get the frame locals
5904 (e.g. the frame at <code>depth</code> is executing a native method).
5905 </error>
5906 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
5907 Thread was not suspended and was not the current thread.
5908 </error>
5909 </errors>
5910 </function>
5924 <capabilities>
5925 <required id="can_access_local_variables"></required>
5926 </capabilities>
5927 <parameters>
5928 <param id="thread">
5929 <jthread null="current" frame="frame" impl="noconvert"/>
5930 <description>
5931 The thread of the frame containing the variable's value.
5932 </description>
5933 </param>
5934 <param id="depth">
5935 <jframeID thread="thread"/>
5936 <description>
5937 The depth of the frame containing the variable's value.
5938 </description>
5939 </param>
5940 <param id="value_ptr">
5941 <outptr><jobject/></outptr>
5942 <description>
5943 On return, points to the variable's value.
5944 </description>
5945 </param>
5946 </parameters>
5947 <errors>
5948 <error id="JVMTI_ERROR_INVALID_SLOT">
5949 If the specified frame is a static method frame.
5950 </error>
5951 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
5952 Thread was not suspended and was not the current thread.
5953 </error>
5954 </errors>
5955 </function>
5956 <function id="GetLocalInt" num="22">
5957 <synopsis>Get Local Variable - Int</synopsis>
5958 <description>
5959 This function can be used to retrieve the value of a local
5960 variable whose type is <code>int</code>,
5961 <code>short</code>, <code>char</code>, <code>byte</code>, or
5962 <code>boolean</code>.
5963 <p/>
13971 </description>
13972 </param>
13973 </parameters>
13974 </event>
13975
13976 <event label="VM Object Allocation"
13977 id="VMObjectAlloc" const="JVMTI_EVENT_VM_OBJECT_ALLOC" num="84">
13978 <description>
13979 Sent when a method causes the virtual machine to directly allocate an
13980 Object visible to Java programming language code.
13981 Generally object allocation should be detected by instrumenting
13982 the bytecodes of allocating methods.
13983 Object allocation generated in native code by JNI function
13984 calls should be detected using
13985 <internallink id="jniIntercept">JNI function interception</internallink>.
13986 Some methods might not have associated bytecodes and are not
13987 native methods, they instead are executed directly by the
13988 VM. These methods should send this event.
13989 Virtual machines which are incapable of bytecode instrumentation
13990 for some or all of their methods can send this event.
13991
13992 Note that the <internallink
13993 id="SampledObjectAlloc">SampledObjectAlloc</internallink>
13994 event is triggered on all Java object allocations, including those
13995 caused by bytecode method execution, JNI method execution, and
13996 directly by VM methods.
13997 <p/>
13998 Typical examples where this event might be sent:
13999 <ul>
14000 <li>Reflection -- for example, <code>java.lang.Class.newInstance()</code></li>
14001 <li>Methods not represented by bytecodes -- for example, VM intrinsics and
14002 J2ME preloaded classes</li>
14003 </ul>
14004 Cases where this event would not be generated:
14005 <ul>
14006 <li>Allocation due to bytecodes -- for example, the <code>new</code>
14007 and <code>newarray</code> VM instructions</li>
14008 <li>Allocation due to JNI function calls -- for example,
14009 <code>AllocObject</code></li>
14010 <li>Allocations during VM initialization</li>
14017 </capabilities>
14018 <parameters>
14019 <param id="jni_env">
14020 <outptr>
14021 <struct>JNIEnv</struct>
14022 </outptr>
14023 <description>
14024 The JNI environment of the event (current) thread
14025 </description>
14026 </param>
14027 <param id="thread">
14028 <jthread/>
14029 <description>
14030 Thread allocating the object.
14031 </description>
14032 </param>
14033 <param id="object">
14034 <jobject/>
14035 <description>
14036 JNI local reference to the object that was allocated.
14037 </description>
14038 </param>
14039 <param id="object_klass">
14040 <jclass/>
14041 <description>
14042 JNI local reference to the class of the object.
14043 </description>
14044 </param>
14045 <param id="size">
14046 <jlong/>
14047 <description>
14048 Size of the object (in bytes). See <functionlink id="GetObjectSize"/>.
14049 </description>
14050 </param>
14051 </parameters>
14052 </event>
14053
14054 <event label="Sampled Object Allocation"
14055 id="SampledObjectAlloc" const="JVMTI_EVENT_SAMPLED_OBJECT_ALLOC" filtered="thread" num="86" since="11">
14056 <description>
14063 When the number of bytes exceeds the sampling interval, it will send another event.
14064 This implies that, on average, one object will be sampled every time a thread has
14065 allocated 512KB bytes since the last sample.
14066 <p/>
14067 Note that the sampler is pseudo-random: it will not sample every 512KB precisely.
14068 The goal of this is to ensure high quality sampling even if allocation is
14069 happening in a fixed pattern (i.e., the same set of objects are being allocated
14070 every 512KB).
14071 <p/>
14072 If another sampling interval is required, the user can call
14073 <functionlink id="SetHeapSamplingInterval"></functionlink> with a strictly positive integer value,
14074 representing the new sampling interval.
14075 <p/>
14076 This event is sent once the sampled allocation has been performed. It provides the object, stack trace
14077 of the allocation, the thread allocating, the size of allocation, and the object's class.
14078 <p/>
14079 A typical use case of this system is to determine where heap allocations originate.
14080 In conjunction with weak references and the function
14081 <functionlink id="GetStackTrace"></functionlink>, a user can track which objects were allocated from which
14082 stack trace, and which are still live during the execution of the program.
14083 </description>
14084 <origin>new</origin>
14085 <capabilities>
14086 <required id="can_generate_sampled_object_alloc_events"></required>
14087 </capabilities>
14088 <parameters>
14089 <param id="jni_env">
14090 <outptr>
14091 <struct>JNIEnv</struct>
14092 </outptr>
14093 <description>
14094 The JNI environment of the event (current) thread.
14095 </description>
14096 </param>
14097 <param id="thread">
14098 <jthread/>
14099 <description>
14100 Thread allocating the object.
14101 </description>
14102 </param>
14103 <param id="object">
14104 <jobject/>
14105 <description>
14106 JNI local reference to the object that was allocated.
14107 </description>
14108 </param>
14109 <param id="object_klass">
14110 <jclass/>
14111 <description>
14112 JNI local reference to the class of the object
14113 </description>
14114 </param>
14115 <param id="size">
14116 <jlong/>
14117 <description>
14118 Size of the object (in bytes). See <functionlink id="GetObjectSize"/>.
14119 </description>
14120 </param>
14121 </parameters>
14122 </event>
14123
14124 <event label="Object Free"
14125 id="ObjectFree" const="JVMTI_EVENT_OBJECT_FREE" num="83">
14126 <description>
14127 An Object Free event is sent when the garbage collector frees an object.
14128 Events are only sent for tagged objects--see
14129 <internallink id="Heap">heap functions</internallink>.
14130 <p/>
14131 The event handler must not use JNI functions and
14132 must not use <jvmti/> functions except those which
14133 specifically allow such use (see the raw monitor, memory management,
14134 and environment local storage functions).
14135 </description>
14136 <origin>new</origin>
14137 <capabilities>
14138 <required id="can_generate_object_free_events"></required>
14139 </capabilities>
14140 <parameters>
14141 <param id="tag">
14142 <jlong/>
14143 <description>
14144 The freed object's tag
14145 </description>
14146 </param>
14147 </parameters>
14148 </event>
14149
14150 <event label="Garbage Collection Start"
14151 id="GarbageCollectionStart" const="JVMTI_EVENT_GARBAGE_COLLECTION_START" num="81">
14152 <description>
14153 A Garbage Collection Start event is sent when a
14154 garbage collection pause begins.
|
1 <?xml version="1.0" encoding="UTF-8"?>
2 <?xml-stylesheet type="text/xsl" href="jvmti.xsl"?>
3 <!--
4 Copyright (c) 2002, 2026, Oracle and/or its affiliates. All rights reserved.
5 DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
6
7 This code is free software; you can redistribute it and/or modify it
8 under the terms of the GNU General Public License version 2 only, as
9 published by the Free Software Foundation.
10
11 This code is distributed in the hope that it will be useful, but WITHOUT
12 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 version 2 for more details (a copy is included in the LICENSE file that
15 accompanied this code).
16
17 You should have received a copy of the GNU General Public License version
18 2 along with this work; if not, write to the Free Software Foundation,
19 Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20
21 Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 or visit www.oracle.com if you need additional information or have any
23 questions.
24 -->
5871 <description>
5872 The thread of the frame containing the variable's value.
5873 </description>
5874 </param>
5875 <param id="depth">
5876 <jframeID thread="thread"/>
5877 <description>
5878 The depth of the frame containing the variable's value.
5879 </description>
5880 </param>
5881 <param id="slot">
5882 <jint/>
5883 <description>
5884 The variable's slot number.
5885 </description>
5886 </param>
5887 <param id="value_ptr">
5888 <outptr><jobject/></outptr>
5889 <description>
5890 On return, points to the variable's value.
5891 When preview features are enabled, if the requested local is the
5892 "<code>this</code>" object, and "<code>this</code>" is a value
5893 object under construction, the value_ptr is set to a snapshot
5894 of the "<code>this</code>" object that represents the value
5895 object's state at the point the snapshot is taken.
5896 </description>
5897 </param>
5898 </parameters>
5899 <errors>
5900 <error id="JVMTI_ERROR_INVALID_SLOT">
5901 Invalid <code>slot</code>.
5902 </error>
5903 <error id="JVMTI_ERROR_TYPE_MISMATCH">
5904 The variable type is not
5905 <code>Object</code> or a subclass of <code>Object</code>.
5906 </error>
5907 <error id="JVMTI_ERROR_OPAQUE_FRAME">
5908 The implementation is unable to get the frame locals
5909 (e.g. the frame at <code>depth</code> is executing a native method).
5910 </error>
5911 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
5912 Thread was not suspended and was not the current thread.
5913 </error>
5914 </errors>
5915 </function>
5929 <capabilities>
5930 <required id="can_access_local_variables"></required>
5931 </capabilities>
5932 <parameters>
5933 <param id="thread">
5934 <jthread null="current" frame="frame" impl="noconvert"/>
5935 <description>
5936 The thread of the frame containing the variable's value.
5937 </description>
5938 </param>
5939 <param id="depth">
5940 <jframeID thread="thread"/>
5941 <description>
5942 The depth of the frame containing the variable's value.
5943 </description>
5944 </param>
5945 <param id="value_ptr">
5946 <outptr><jobject/></outptr>
5947 <description>
5948 On return, points to the variable's value.
5949 When preview features are enabled, and the local instance is a value
5950 object under construction, the value_ptr is set to a snapshot
5951 of the "<code>this</code>" object that represents the value
5952 object's state at the point the snapshot is taken.
5953 </description>
5954 </param>
5955 </parameters>
5956 <errors>
5957 <error id="JVMTI_ERROR_INVALID_SLOT">
5958 If the specified frame is a static method frame.
5959 </error>
5960 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
5961 Thread was not suspended and was not the current thread.
5962 </error>
5963 </errors>
5964 </function>
5965 <function id="GetLocalInt" num="22">
5966 <synopsis>Get Local Variable - Int</synopsis>
5967 <description>
5968 This function can be used to retrieve the value of a local
5969 variable whose type is <code>int</code>,
5970 <code>short</code>, <code>char</code>, <code>byte</code>, or
5971 <code>boolean</code>.
5972 <p/>
13980 </description>
13981 </param>
13982 </parameters>
13983 </event>
13984
13985 <event label="VM Object Allocation"
13986 id="VMObjectAlloc" const="JVMTI_EVENT_VM_OBJECT_ALLOC" num="84">
13987 <description>
13988 Sent when a method causes the virtual machine to directly allocate an
13989 Object visible to Java programming language code.
13990 Generally object allocation should be detected by instrumenting
13991 the bytecodes of allocating methods.
13992 Object allocation generated in native code by JNI function
13993 calls should be detected using
13994 <internallink id="jniIntercept">JNI function interception</internallink>.
13995 Some methods might not have associated bytecodes and are not
13996 native methods, they instead are executed directly by the
13997 VM. These methods should send this event.
13998 Virtual machines which are incapable of bytecode instrumentation
13999 for some or all of their methods can send this event.
14000 When preview features are enabled and the allocated object has no identity,
14001 <code>null</code> is passed for the <paramlink id="object"></paramlink> parameter.
14002
14003 Note that the <internallink
14004 id="SampledObjectAlloc">SampledObjectAlloc</internallink>
14005 event is triggered on all Java object allocations, including those
14006 caused by bytecode method execution, JNI method execution, and
14007 directly by VM methods.
14008 <p/>
14009 Typical examples where this event might be sent:
14010 <ul>
14011 <li>Reflection -- for example, <code>java.lang.Class.newInstance()</code></li>
14012 <li>Methods not represented by bytecodes -- for example, VM intrinsics and
14013 J2ME preloaded classes</li>
14014 </ul>
14015 Cases where this event would not be generated:
14016 <ul>
14017 <li>Allocation due to bytecodes -- for example, the <code>new</code>
14018 and <code>newarray</code> VM instructions</li>
14019 <li>Allocation due to JNI function calls -- for example,
14020 <code>AllocObject</code></li>
14021 <li>Allocations during VM initialization</li>
14028 </capabilities>
14029 <parameters>
14030 <param id="jni_env">
14031 <outptr>
14032 <struct>JNIEnv</struct>
14033 </outptr>
14034 <description>
14035 The JNI environment of the event (current) thread
14036 </description>
14037 </param>
14038 <param id="thread">
14039 <jthread/>
14040 <description>
14041 Thread allocating the object.
14042 </description>
14043 </param>
14044 <param id="object">
14045 <jobject/>
14046 <description>
14047 JNI local reference to the object that was allocated.
14048 Null when preview features are enabled and the allocated object has no identity.
14049 </description>
14050 </param>
14051 <param id="object_klass">
14052 <jclass/>
14053 <description>
14054 JNI local reference to the class of the object.
14055 </description>
14056 </param>
14057 <param id="size">
14058 <jlong/>
14059 <description>
14060 Size of the object (in bytes). See <functionlink id="GetObjectSize"/>.
14061 </description>
14062 </param>
14063 </parameters>
14064 </event>
14065
14066 <event label="Sampled Object Allocation"
14067 id="SampledObjectAlloc" const="JVMTI_EVENT_SAMPLED_OBJECT_ALLOC" filtered="thread" num="86" since="11">
14068 <description>
14075 When the number of bytes exceeds the sampling interval, it will send another event.
14076 This implies that, on average, one object will be sampled every time a thread has
14077 allocated 512KB bytes since the last sample.
14078 <p/>
14079 Note that the sampler is pseudo-random: it will not sample every 512KB precisely.
14080 The goal of this is to ensure high quality sampling even if allocation is
14081 happening in a fixed pattern (i.e., the same set of objects are being allocated
14082 every 512KB).
14083 <p/>
14084 If another sampling interval is required, the user can call
14085 <functionlink id="SetHeapSamplingInterval"></functionlink> with a strictly positive integer value,
14086 representing the new sampling interval.
14087 <p/>
14088 This event is sent once the sampled allocation has been performed. It provides the object, stack trace
14089 of the allocation, the thread allocating, the size of allocation, and the object's class.
14090 <p/>
14091 A typical use case of this system is to determine where heap allocations originate.
14092 In conjunction with weak references and the function
14093 <functionlink id="GetStackTrace"></functionlink>, a user can track which objects were allocated from which
14094 stack trace, and which are still live during the execution of the program.
14095 When preview features are enabled and the allocated object has no identity,
14096 <code>null</code> is passed for the <paramlink id="object"></paramlink> parameter.
14097 Note that weak references support identity objects only.
14098 </description>
14099 <origin>new</origin>
14100 <capabilities>
14101 <required id="can_generate_sampled_object_alloc_events"></required>
14102 </capabilities>
14103 <parameters>
14104 <param id="jni_env">
14105 <outptr>
14106 <struct>JNIEnv</struct>
14107 </outptr>
14108 <description>
14109 The JNI environment of the event (current) thread.
14110 </description>
14111 </param>
14112 <param id="thread">
14113 <jthread/>
14114 <description>
14115 Thread allocating the object.
14116 </description>
14117 </param>
14118 <param id="object">
14119 <jobject/>
14120 <description>
14121 JNI local reference to the object that was allocated.
14122 Null when preview features are enabled and the allocated object has no identity.
14123 </description>
14124 </param>
14125 <param id="object_klass">
14126 <jclass/>
14127 <description>
14128 JNI local reference to the class of the object
14129 </description>
14130 </param>
14131 <param id="size">
14132 <jlong/>
14133 <description>
14134 Size of the object (in bytes). See <functionlink id="GetObjectSize"/>.
14135 </description>
14136 </param>
14137 </parameters>
14138 </event>
14139
14140 <event label="Object Free"
14141 id="ObjectFree" const="JVMTI_EVENT_OBJECT_FREE" num="83">
14142 <description>
14143 An Object Free event is sent when the garbage collector frees an object.
14144 Events are only sent for tagged objects--see
14145 <internallink id="Heap">heap functions</internallink>.
14146 <p/>
14147 The event handler must not use JNI functions and
14148 must not use <jvmti/> functions except those which
14149 specifically allow such use (see the raw monitor, memory management,
14150 and environment local storage functions).
14151 When preview features are enabled, this event does not support value object allocations.
14152 </description>
14153 <origin>new</origin>
14154 <capabilities>
14155 <required id="can_generate_object_free_events"></required>
14156 </capabilities>
14157 <parameters>
14158 <param id="tag">
14159 <jlong/>
14160 <description>
14161 The freed object's tag
14162 </description>
14163 </param>
14164 </parameters>
14165 </event>
14166
14167 <event label="Garbage Collection Start"
14168 id="GarbageCollectionStart" const="JVMTI_EVENT_GARBAGE_COLLECTION_START" num="81">
14169 <description>
14170 A Garbage Collection Start event is sent when a
14171 garbage collection pause begins.
|