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 -->
908 </intro>
909
910 <intro id="context" label="Specification Context">
911 Since this interface provides access to the state of applications running in the
912 Java virtual machine;
913 terminology refers to the Java platform and not the native
914 platform (unless stated otherwise). For example:
915 <ul>
916 <li>"thread" means Java programming language thread.</li>
917 <li>"stack frame" means Java virtual machine stack frame.</li>
918 <li>"class" means Java programming language class.</li>
919 <li>"heap" means Java virtual machine heap.</li>
920 <li>"monitor" means Java programming language object monitor.</li>
921 </ul>
922 <p/>
923 Sun, Sun Microsystems, the Sun logo, Java, and JVM
924 are trademarks or registered trademarks of Oracle
925 and/or its affiliates, in the U.S. and other countries.
926 </intro>
927
928
929 <functionsection label="Functions">
930 <intro id="jvmtiEnvAccess" label="Accessing Functions">
931 Native code accesses <jvmti/> features
932 by calling <jvmti/> functions.
933 Access to <jvmti/> functions is by use of an interface pointer
934 in the same manner as
935 <externallink id="jni/design.html">Java
936 Native Interface (JNI) functions</externallink> are accessed.
937 The <jvmti/> interface pointer is called the
938 <i>environment pointer</i>.
939 <p/>
940 An environment pointer is a pointer to an environment and has
941 the type <code>jvmtiEnv*</code>.
942 An environment has information about its <jvmti/> connection.
943 The first value in the environment is a pointer to the function table.
944 The function table is an array of pointers to <jvmti/> functions.
945 Every function pointer is at a predefined offset inside the
946 array.
947 <p/>
3359 <errors>
3360 <error id="JVMTI_ERROR_OPAQUE_FRAME">
3361 The implementation is unable to force the current frame to return
3362 (e.g. current frame is executing a native method).
3363 </error>
3364 <error id="JVMTI_ERROR_TYPE_MISMATCH">
3365 The result type of the called method is not <code>double</code>.
3366 </error>
3367 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
3368 Thread was not suspended and was not the current thread.
3369 </error>
3370 <error id="JVMTI_ERROR_NO_MORE_FRAMES">
3371 There are no frames on the call stack.
3372 </error>
3373 </errors>
3374 </function>
3375
3376 <function id="ForceEarlyReturnVoid" num="86" since="1.1">
3377 <synopsis>Force Early Return - Void</synopsis>
3378 <description>
3379 This function can be used to return from a method with no result type.
3380 That is, the called method must be declared <code>void</code>.
3381 </description>
3382 <origin>new</origin>
3383 <capabilities>
3384 <required id="can_force_early_return"></required>
3385 </capabilities>
3386 <parameters>
3387 <param id="thread">
3388 <jthread null="current" impl="noconvert"/>
3389 <description>
3390 The thread whose current frame is to return early.
3391 </description>
3392 </param>
3393 </parameters>
3394 <errors>
3395 <error id="JVMTI_ERROR_OPAQUE_FRAME">
3396 The implementation is unable to force the current frame to return
3397 (e.g. current frame is executing a native method).
3398 </error>
3399 <error id="JVMTI_ERROR_TYPE_MISMATCH">
3400 The called method has a result type.
3401 </error>
3402 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
3403 Thread was not suspended and was not the current thread.
3404 </error>
3405 <error id="JVMTI_ERROR_NO_MORE_FRAMES">
3406 There are no frames on the call stack.
3407 </error>
3408 </errors>
3409 </function>
3410
3411 </category>
3412
3413 <category id="Heap" label="Heap">
3414 <intro>
3415 These functions are used to analyze the heap.
3416 Functionality includes the ability to view the objects in the
3417 heap and to tag these objects.
3418 </intro>
3419
3420 <intro id="objectTags" label="Object Tags">
3421 A <i>tag</i> is a value associated with an object.
3422 Tags are explicitly set by the agent using the
3423 <functionlink id="SetTag"></functionlink> function or by
3424 callback functions such as <functionlink id="jvmtiHeapIterationCallback"/>.
3425 <p/>
3426 Tags are local to the environment; that is, the tags of one
3427 environment are not visible in another.
3428 <p/>
3429 Tags are <code>jlong</code> values which can be used
3430 simply to mark an object or to store a pointer to more detailed
3431 information. Objects which have not been tagged have a
3432 tag of zero.
3433 Setting a tag to zero makes the object untagged.
3434 </intro>
3435
3436 <intro id="heapCallbacks" label="Heap Callback Functions">
3437 Heap functions which iterate through the heap and recursively
3438 follow object references use agent supplied callback functions
3439 to deliver the information.
3440 <p/>
3441 These heap callback functions must adhere to the following restrictions --
3442 These callbacks must not use JNI functions.
3443 These callbacks must not use <jvmti/> functions except
3444 <i>callback safe</i> functions which
3445 specifically allow such use (see the raw monitor, memory management,
3446 and environment local storage functions).
3447 <p/>
3448 An implementation may invoke a callback on an internal thread or
3449 the thread which called the iteration function.
3450 Heap callbacks are single threaded -- no more than one callback will
3451 be invoked at a time.
3452 <p/>
3453 The Heap Filter Flags can be used to prevent reporting
5842 These functions are used to retrieve or set the value of a local variable.
5843 The variable is identified by the depth of the frame containing its
5844 value and the variable's slot number within that frame.
5845 The mapping of variables to
5846 slot numbers can be obtained with the function
5847 <functionlink id="GetLocalVariableTable"></functionlink>.
5848 <p/>
5849 The <code>GetLocalXXX</code> functions may be used to retrieve the value of
5850 a local variable contained in the frame of a virtual thread.
5851 The <code>SetLocalXXX</code> functions may be used to set the value of a
5852 local variable in the topmost frame of a virtual thread suspended at an event.
5853 An implementation may support setting locals in other cases.
5854 </intro>
5855
5856 <function id="GetLocalObject" num="21">
5857 <synopsis>Get Local Variable - Object</synopsis>
5858 <description>
5859 This function can be used to retrieve the value of a local
5860 variable whose type is <code>Object</code> or a subclass of <code>Object</code>.
5861 <p/>
5862 The specified thread must be suspended or must be the current thread.
5863 </description>
5864 <origin>jvmdi</origin>
5865 <capabilities>
5866 <required id="can_access_local_variables"></required>
5867 </capabilities>
5868 <parameters>
5869 <param id="thread">
5870 <jthread null="current" frame="frame" impl="noconvert"/>
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>
5911
5912 <function id="GetLocalInstance" num="155" since="1.2">
5913 <synopsis>Get Local Instance</synopsis>
5914 <description>
5915 This function can be used to retrieve the value of the local object
5916 variable at slot 0 (the "<code>this</code>" object) from non-static
5917 frames. This function can retrieve the "<code>this</code>" object from
5918 native method frames, whereas <code>GetLocalObject()</code> would
5919 return <code>JVMTI_ERROR_OPAQUE_FRAME</code> in those cases.
5920 <p/>
5921 The specified thread must be suspended or must be the current thread.
5922 </description>
5923 <origin>new</origin>
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/>
7335 </param>
7336 <param id="source_name_ptr">
7337 <allocbuf><char/></allocbuf>
7338 <description>
7339 On return, points to the class's source file name, encoded as a
7340 <internallink id="mUTF">modified UTF-8</internallink> string.
7341 </description>
7342 </param>
7343 </parameters>
7344 <errors>
7345 <error id="JVMTI_ERROR_ABSENT_INFORMATION">
7346 Class information does not include a source file name. This includes
7347 cases where the class is an array class or primitive class.
7348 </error>
7349 </errors>
7350 </function>
7351
7352 <function id="GetClassModifiers" phase="start" num="51">
7353 <synopsis>Get Class Modifiers</synopsis>
7354 <description>
7355 For the class indicated by <code>klass</code>, return the access
7356 flags
7357 via <code>modifiers_ptr</code>.
7358 Access flags are defined in <vmspec chapter="4"/>.
7359 <p/>
7360 If the class is an array class, then its public, private, and protected
7361 modifiers are the same as those of its component type. For arrays of
7362 primitives, this component type is represented by one of the primitive
7363 classes (for example, <code>java.lang.Integer.TYPE</code>).
7364 <p/>
7365 If the class is a primitive class, its public modifier is always true,
7366 and its protected and private modifiers are always false.
7367 <p/>
7368 If the class is an array class or a primitive class then its final
7369 modifier is always true and its interface modifier is always false.
7370 The values of its other modifiers are not determined by this specification.
7371
7372 </description>
7373 <origin>jvmdi</origin>
7374 <capabilities>
7375 </capabilities>
7376 <parameters>
7377 <param id="klass">
7378 <jclass/>
7379 <description>
7380 The class to query.
7381 </description>
7382 </param>
7383 <param id="modifiers_ptr">
7384 <outptr><jint/></outptr>
7385 <description>
7386 On return, points to the current access flags of this class.
7387
7388 </description>
7389 </param>
7390 </parameters>
7391 <errors>
7392 </errors>
7393 </function>
7394
7395 <function id="GetClassMethods" phase="start" num="52">
7396 <synopsis>Get Class Methods</synopsis>
7397 <description>
7398 For the class indicated by <code>klass</code>, return a count of
7399 methods via <code>method_count_ptr</code> and a list of
7400 method IDs via <code>methods_ptr</code>. The method list contains
7401 constructors and static initializers as well as true methods.
7402 Only directly declared methods are returned (not inherited methods).
7403 An empty method list is returned for array classes and primitive classes
7404 (for example, <code>java.lang.Integer.TYPE</code>).
7405 </description>
7406 <origin>jvmdi</origin>
8269 <field id="notify_waiter_count">
8270 <jint/>
8271 <description>
8272 The number of platform threads waiting to own this monitor, or <code>0</code>
8273 if only virtual threads are waiting to be notified or no threads are waiting
8274 to be notified
8275 </description>
8276 </field>
8277 <field id="notify_waiters">
8278 <allocfieldbuf><jthread/></allocfieldbuf>
8279 <description>
8280 The <code>notify_waiter_count</code> platform threads waiting to be notified
8281 </description>
8282 </field>
8283 </typedef>
8284 <description>
8285 Get information about the object's monitor.
8286 The fields of the <functionlink id="jvmtiMonitorUsage"></functionlink> structure
8287 are filled in with information about usage of the monitor.
8288 <p/>
8289 <b> This function does not support getting information about an object's monitor
8290 when it is owned by a virtual thread. It also does not support returning a
8291 reference to virtual threads that are waiting to own a monitor or waiting to
8292 be notified.
8293 </b>
8294 <todo>
8295 Decide and then clarify suspend requirements.
8296 </todo>
8297 </description>
8298 <origin>jvmdi</origin>
8299 <capabilities>
8300 <required id="can_get_monitor_info"></required>
8301 </capabilities>
8302 <parameters>
8303 <param id="object">
8304 <jobject/>
8305 <description>
8306 The object to query.
8307 </description>
8308 </param>
10668 </capabilityfield>
10669 <capabilityfield id="can_generate_sampled_object_alloc_events" since="11">
10670 <description>
10671 Can generate sampled allocation events.
10672 If this capability is enabled then the heap sampling method
10673 <functionlink id="SetHeapSamplingInterval"></functionlink> can be
10674 called and <eventlink id="SampledObjectAlloc"></eventlink> events can be generated.
10675 </description>
10676 </capabilityfield>
10677 <capabilityfield id="can_support_virtual_threads" since="21">
10678 <description>
10679 Can support virtual threads.
10680 If this capability is enabled then the following functions can be called:
10681 <functionlink id="SuspendAllVirtualThreads"></functionlink>,
10682 <functionlink id="ResumeAllVirtualThreads"></functionlink>,
10683 and the following events can be enabled:
10684 <eventlink id="VirtualThreadStart"></eventlink>,
10685 <eventlink id="VirtualThreadEnd"></eventlink>.
10686 </description>
10687 </capabilityfield>
10688 </capabilitiestypedef>
10689
10690 <function id="GetPotentialCapabilities" jkernel="yes" phase="onload" num="140">
10691 <synopsis>Get Potential Capabilities</synopsis>
10692 <description>
10693 Returns via <paramlink id="capabilities_ptr"></paramlink> the <jvmti/>
10694 features that can potentially be possessed by this environment
10695 at this time.
10696 The returned capabilities differ from the complete set of capabilities
10697 implemented by the VM in two cases: another environment possesses
10698 capabilities that can only be possessed by one environment, or the
10699 current <functionlink id="GetPhase">phase</functionlink> is live,
10700 and certain capabilities can only be added during the <code>OnLoad</code> phase.
10701 The <functionlink id="AddCapabilities"></functionlink> function
10702 may be used to set any or all or these capabilities.
10703 Currently possessed capabilities are included.
10704 <p/>
10705 Typically this function is used in the <code>OnLoad</code> function.
10706 Some virtual machines may allow a limited set of capabilities to be
10707 added in the live phase.
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>
14011 <li>VM internal objects</li>
14012 </ul>
14013 </description>
14014 <origin>new</origin>
14015 <capabilities>
14016 <required id="can_generate_vm_object_alloc_events"></required>
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"
15453 implementation may choose to not call the Agent_OnUnload function
15454 if the Agent_OnAttach/Agent_OnAttach_L function reported an error.
15455 </change>
15456 <change date="8 June 2021" version="17.0.0">
15457 Minor update to deprecate Heap functions 1.0.
15458 </change>
15459 <change date="27 April 2022" version="19.0.0">
15460 Support for virtual threads (Preview):
15461 Add new capability: can_support_virtual_threads.
15462 Add new functions: SuspendAllVirtualThreads, ResumeAllVirtualThreads.
15463 Add new event types: JVMTI_EVENT_VIRTUAL_THREAD_START, JVMTI_EVENT_VIRTUAL_THREAD_END.
15464 Add new error code: JVMTI_ERROR_UNSUPPORTED_OPERATION.
15465 </change>
15466 <change date="7 June 2023" version="21.0.0">
15467 Virtual threads finalized to be a permanent feature.
15468 Agent start-up in the live phase now specified to print a warning.
15469 </change>
15470 <change date="10 January 2025" version="25.0.0">
15471 Add new function ClearAllFramePops. Needed to speedup debugger single stepping.
15472 </change>
15473 </changehistory>
15474
15475 </specification>
15476 <!-- Keep this comment at the end of the file
15477 Local variables:
15478 mode: sgml
15479 sgml-omittag:t
15480 sgml-shorttag:t
15481 sgml-namecase-general:t
15482 sgml-general-insert-case:lower
15483 sgml-minimize-attributes:nil
15484 sgml-always-quote-attributes:t
15485 sgml-indent-step:2
15486 sgml-indent-data:t
15487 sgml-parent-document:nil
15488 sgml-exposed-tags:nil
15489 sgml-local-catalogs:nil
15490 sgml-local-ecat-files:nil
15491 End:
15492 -->
|
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 -->
908 </intro>
909
910 <intro id="context" label="Specification Context">
911 Since this interface provides access to the state of applications running in the
912 Java virtual machine;
913 terminology refers to the Java platform and not the native
914 platform (unless stated otherwise). For example:
915 <ul>
916 <li>"thread" means Java programming language thread.</li>
917 <li>"stack frame" means Java virtual machine stack frame.</li>
918 <li>"class" means Java programming language class.</li>
919 <li>"heap" means Java virtual machine heap.</li>
920 <li>"monitor" means Java programming language object monitor.</li>
921 </ul>
922 <p/>
923 Sun, Sun Microsystems, the Sun logo, Java, and JVM
924 are trademarks or registered trademarks of Oracle
925 and/or its affiliates, in the U.S. and other countries.
926 </intro>
927
928 <intro id="identityAndValueObjects" label="Identity and Value Objects">
929 If preview features are enabled then some Java objects will have identity and others
930 (instances of value classes) will not. <jvmti/> makes no distinction between these cases
931 in general, but some specific functions will behave differently if invoked upon
932 a Java object that does not have identity. Such differences in behavior are described
933 by the individual functions and events where they apply.
934 <p/>
935 In summary, tags for value objects use value equality semantics, and
936 the <eventlink id="ObjectFree"/> event is not sent for tagged value objects.
937 The <eventlink id="VMObjectAlloc"/> and <eventlink id="SampledObjectAlloc"/> events
938 are only sent for value objects if the
939 <fieldlink id="can_support_value_objects" struct="jvmtiCapabilities"/>
940 capability is possessed.
941 <p/>
942 Value objects can also affect class and interface property queries, monitor information,
943 and <jvmti/> functions that operate on value class constructor frames.
944 </intro>
945
946 <functionsection label="Functions">
947 <intro id="jvmtiEnvAccess" label="Accessing Functions">
948 Native code accesses <jvmti/> features
949 by calling <jvmti/> functions.
950 Access to <jvmti/> functions is by use of an interface pointer
951 in the same manner as
952 <externallink id="jni/design.html">Java
953 Native Interface (JNI) functions</externallink> are accessed.
954 The <jvmti/> interface pointer is called the
955 <i>environment pointer</i>.
956 <p/>
957 An environment pointer is a pointer to an environment and has
958 the type <code>jvmtiEnv*</code>.
959 An environment has information about its <jvmti/> connection.
960 The first value in the environment is a pointer to the function table.
961 The function table is an array of pointers to <jvmti/> functions.
962 Every function pointer is at a predefined offset inside the
963 array.
964 <p/>
3376 <errors>
3377 <error id="JVMTI_ERROR_OPAQUE_FRAME">
3378 The implementation is unable to force the current frame to return
3379 (e.g. current frame is executing a native method).
3380 </error>
3381 <error id="JVMTI_ERROR_TYPE_MISMATCH">
3382 The result type of the called method is not <code>double</code>.
3383 </error>
3384 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
3385 Thread was not suspended and was not the current thread.
3386 </error>
3387 <error id="JVMTI_ERROR_NO_MORE_FRAMES">
3388 There are no frames on the call stack.
3389 </error>
3390 </errors>
3391 </function>
3392
3393 <function id="ForceEarlyReturnVoid" num="86" since="1.1">
3394 <synopsis>Force Early Return - Void</synopsis>
3395 <description>
3396 This function can be used to return from a method with a return type
3397 of <code>void</code>.
3398 A constructor is a special method named <code><init></code> with
3399 a return type of <code>void</code>. A class initializer is a special
3400 method named <code><clinit></code> with a return type of
3401 <code>void</code>.
3402 <p/>
3403 When preview features are enabled, this function can not be used to return
3404 early from the constructor of a value class.
3405 </description>
3406 <origin>new</origin>
3407 <capabilities>
3408 <required id="can_force_early_return"></required>
3409 </capabilities>
3410 <parameters>
3411 <param id="thread">
3412 <jthread null="current" impl="noconvert"/>
3413 <description>
3414 The thread whose current frame is to return early.
3415 </description>
3416 </param>
3417 </parameters>
3418 <errors>
3419 <error id="JVMTI_ERROR_OPAQUE_FRAME">
3420 The implementation is unable to force the current frame to return
3421 (e.g. current frame is executing a native method or if preview features
3422 are enabled, the current frame is the constructor for a value class)
3423 </error>
3424 <error id="JVMTI_ERROR_TYPE_MISMATCH">
3425 The called method has a result type.
3426 </error>
3427 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
3428 Thread was not suspended and was not the current thread.
3429 </error>
3430 <error id="JVMTI_ERROR_NO_MORE_FRAMES">
3431 There are no frames on the call stack.
3432 </error>
3433 </errors>
3434 </function>
3435
3436 </category>
3437
3438 <category id="Heap" label="Heap">
3439 <intro>
3440 These functions are used to analyze the heap.
3441 Functionality includes the ability to view the objects in the
3442 heap and to tag these objects.
3443 </intro>
3444
3445 <intro id="objectTags" label="Object Tags">
3446 A <i>tag</i> is a value associated with an object.
3447 Tags are explicitly set by the agent using the
3448 <functionlink id="SetTag"></functionlink> function or by
3449 callback functions such as <functionlink id="jvmtiHeapIterationCallback"/>.
3450 <p/>
3451 Tags are local to the environment; that is, the tags of one
3452 environment are not visible in another.
3453 <p/>
3454 Tags are <code>jlong</code> values which can be used
3455 simply to mark an object or to store a pointer to more detailed
3456 information. Objects which have not been tagged have a
3457 tag of zero.
3458 Setting a tag to zero makes the object untagged.
3459 <p/>
3460 If the <eventlink id="ObjectFree"/> event is enabled then an Object Free
3461 event is sent for tagged objects when the garbage collector frees the object.
3462 When preview features are enabled, the Object Free event is only sent for tagged
3463 <externallink id="jni/functions.html#hasidentity">identity objects</externallink>.
3464 <b>The event is not sent for tagged value objects.</b>
3465 </intro>
3466
3467 <intro id="heapCallbacks" label="Heap Callback Functions">
3468 Heap functions which iterate through the heap and recursively
3469 follow object references use agent supplied callback functions
3470 to deliver the information.
3471 <p/>
3472 These heap callback functions must adhere to the following restrictions --
3473 These callbacks must not use JNI functions.
3474 These callbacks must not use <jvmti/> functions except
3475 <i>callback safe</i> functions which
3476 specifically allow such use (see the raw monitor, memory management,
3477 and environment local storage functions).
3478 <p/>
3479 An implementation may invoke a callback on an internal thread or
3480 the thread which called the iteration function.
3481 Heap callbacks are single threaded -- no more than one callback will
3482 be invoked at a time.
3483 <p/>
3484 The Heap Filter Flags can be used to prevent reporting
5873 These functions are used to retrieve or set the value of a local variable.
5874 The variable is identified by the depth of the frame containing its
5875 value and the variable's slot number within that frame.
5876 The mapping of variables to
5877 slot numbers can be obtained with the function
5878 <functionlink id="GetLocalVariableTable"></functionlink>.
5879 <p/>
5880 The <code>GetLocalXXX</code> functions may be used to retrieve the value of
5881 a local variable contained in the frame of a virtual thread.
5882 The <code>SetLocalXXX</code> functions may be used to set the value of a
5883 local variable in the topmost frame of a virtual thread suspended at an event.
5884 An implementation may support setting locals in other cases.
5885 </intro>
5886
5887 <function id="GetLocalObject" num="21">
5888 <synopsis>Get Local Variable - Object</synopsis>
5889 <description>
5890 This function can be used to retrieve the value of a local
5891 variable whose type is <code>Object</code> or a subclass of <code>Object</code>.
5892 <p/>
5893 When preview features are enabled, if the local is the "<code>this</code>"
5894 object and "<code>this</code>" is a value object under construction, the
5895 function retrieves a snapshot of the "<code>this</code>" object representing
5896 the value object's state at the point the snapshot is taken.
5897 <p/>
5898 The specified thread must be suspended or must be the current thread.
5899 </description>
5900 <origin>jvmdi</origin>
5901 <capabilities>
5902 <required id="can_access_local_variables"></required>
5903 </capabilities>
5904 <parameters>
5905 <param id="thread">
5906 <jthread null="current" frame="frame" impl="noconvert"/>
5907 <description>
5908 The thread of the frame containing the variable's value.
5909 </description>
5910 </param>
5911 <param id="depth">
5912 <jframeID thread="thread"/>
5913 <description>
5914 The depth of the frame containing the variable's value.
5915 </description>
5916 </param>
5917 <param id="slot">
5918 <jint/>
5919 <description>
5920 The variable's slot number.
5921 </description>
5922 </param>
5923 <param id="value_ptr">
5924 <outptr><jobject/></outptr>
5925 <description>
5926 On return, points to the variable's value.
5927 When preview features are enabled, if the local is the "<code>this</code>"
5928 object and "<code>this</code>" is a value object under construction,
5929 <code>value_ptr</code> will point to a snapshot of the "<code>this</code>"
5930 object representing the value object's state at the point the snapshot
5931 is taken.
5932 </description>
5933 </param>
5934 </parameters>
5935 <errors>
5936 <error id="JVMTI_ERROR_INVALID_SLOT">
5937 Invalid <code>slot</code>.
5938 </error>
5939 <error id="JVMTI_ERROR_TYPE_MISMATCH">
5940 The variable type is not
5941 <code>Object</code> or a subclass of <code>Object</code>.
5942 </error>
5943 <error id="JVMTI_ERROR_OPAQUE_FRAME">
5944 The implementation is unable to get the frame locals
5945 (e.g. the frame at <code>depth</code> is executing a native method).
5946 </error>
5947 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
5948 Thread was not suspended and was not the current thread.
5949 </error>
5950 </errors>
5951 </function>
5952
5953 <function id="GetLocalInstance" num="155" since="1.2">
5954 <synopsis>Get Local Instance</synopsis>
5955 <description>
5956 This function can be used to retrieve the value of the local object
5957 variable at slot 0 (the "<code>this</code>" object) from non-static
5958 frames. This function can retrieve the "<code>this</code>" object from
5959 native method frames, whereas <code>GetLocalObject()</code> would
5960 return <code>JVMTI_ERROR_OPAQUE_FRAME</code> in those cases.
5961 <p/>
5962 When preview features are enabled and the "<code>this</code>" object is
5963 a value object under construction, the function retrieves a snapshot of the
5964 "<code>this</code>" object that represents the value object's state at
5965 the point the snapshot is taken.
5966 <p/>
5967 The specified thread must be suspended or must be the current thread.
5968 </description>
5969 <origin>new</origin>
5970 <capabilities>
5971 <required id="can_access_local_variables"></required>
5972 </capabilities>
5973 <parameters>
5974 <param id="thread">
5975 <jthread null="current" frame="frame" impl="noconvert"/>
5976 <description>
5977 The thread of the frame containing the variable's value.
5978 </description>
5979 </param>
5980 <param id="depth">
5981 <jframeID thread="thread"/>
5982 <description>
5983 The depth of the frame containing the variable's value.
5984 </description>
5985 </param>
5986 <param id="value_ptr">
5987 <outptr><jobject/></outptr>
5988 <description>
5989 On return, points to the variable's value.
5990 When preview features are enabled, and the "<code>this</code>" object is
5991 a value object under construction, <code>value_ptr</code> will point to
5992 a snapshot of the "<code>this</code>" object representing the value
5993 object's state at the point the snapshot is taken.
5994 </description>
5995 </param>
5996 </parameters>
5997 <errors>
5998 <error id="JVMTI_ERROR_INVALID_SLOT">
5999 If the specified frame is a static method frame.
6000 </error>
6001 <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
6002 Thread was not suspended and was not the current thread.
6003 </error>
6004 </errors>
6005 </function>
6006 <function id="GetLocalInt" num="22">
6007 <synopsis>Get Local Variable - Int</synopsis>
6008 <description>
6009 This function can be used to retrieve the value of a local
6010 variable whose type is <code>int</code>,
6011 <code>short</code>, <code>char</code>, <code>byte</code>, or
6012 <code>boolean</code>.
6013 <p/>
7385 </param>
7386 <param id="source_name_ptr">
7387 <allocbuf><char/></allocbuf>
7388 <description>
7389 On return, points to the class's source file name, encoded as a
7390 <internallink id="mUTF">modified UTF-8</internallink> string.
7391 </description>
7392 </param>
7393 </parameters>
7394 <errors>
7395 <error id="JVMTI_ERROR_ABSENT_INFORMATION">
7396 Class information does not include a source file name. This includes
7397 cases where the class is an array class or primitive class.
7398 </error>
7399 </errors>
7400 </function>
7401
7402 <function id="GetClassModifiers" phase="start" num="51">
7403 <synopsis>Get Class Modifiers</synopsis>
7404 <description>
7405 For the class indicated by <code>klass</code>, return the Java language
7406 modifiers and class/interface properties of the corresponding
7407 <code>java.lang.Class</code> object, via <code>modifiers_ptr</code>.
7408 <p/>
7409 The modifiers are encoded as a mask of access-flag bit values defined in
7410 <vmspec chapter="4"/>. The returned value is not necessarily the value of the
7411 access_flags item in the class file of <code>klass</code>.
7412 In particular, for member, local, or anonymous classes and interfaces, the result
7413 may include modifiers represented by access flags from the <code>InnerClasses</code>
7414 attribute, such as <code>ACC_STATIC</code>.
7415 <p/>
7416 The modifiers include, as applicable, the Java Virtual Machine constants for
7417 public, private, protected, final, static, abstract, and interface, as well as
7418 access-flag bit values for other class/interface properties encoded in the
7419 result of invoking <code>java.lang.Class.getModifiers()</code> on the
7420 corresponding <code>java.lang.Class</code> object.
7421 <p/>
7422 If <code>klass</code> is an array class, then its public, private, and
7423 protected modifiers are the same as those of its component type. For arrays of
7424 primitives, this component type is represented by one of the primitive
7425 classes, such as <code>java.lang.Integer.TYPE</code>. For array classes, the
7426 abstract and final modifiers are set, and the interface modifier is not set.
7427 <p/>
7428 If <code>klass</code> is a primitive type or void, then its public, abstract,
7429 and final modifiers are always set, and its protected, private, and interface
7430 modifiers are never set.
7431 <p/>
7432 When preview features are enabled, the <code>ACC_IDENTITY</code> access flag
7433 is set if and only if <code>klass</code> is an identity class or an array class.
7434 <p/>
7435 When preview features are disabled, the <code>ACC_SUPER</code> access flag may be
7436 set only if <code>klass</code> is not a primitive type or void. The flag has no
7437 effective meaning.
7438 </description>
7439 <origin>jvmdi</origin>
7440 <capabilities>
7441 </capabilities>
7442 <parameters>
7443 <param id="klass">
7444 <jclass/>
7445 <description>
7446 The class to query.
7447 </description>
7448 </param>
7449 <param id="modifiers_ptr">
7450 <outptr><jint/></outptr>
7451 <description>
7452 On return, points to the modifiers of this class.
7453
7454 </description>
7455 </param>
7456 </parameters>
7457 <errors>
7458 </errors>
7459 </function>
7460
7461 <function id="GetClassMethods" phase="start" num="52">
7462 <synopsis>Get Class Methods</synopsis>
7463 <description>
7464 For the class indicated by <code>klass</code>, return a count of
7465 methods via <code>method_count_ptr</code> and a list of
7466 method IDs via <code>methods_ptr</code>. The method list contains
7467 constructors and static initializers as well as true methods.
7468 Only directly declared methods are returned (not inherited methods).
7469 An empty method list is returned for array classes and primitive classes
7470 (for example, <code>java.lang.Integer.TYPE</code>).
7471 </description>
7472 <origin>jvmdi</origin>
8335 <field id="notify_waiter_count">
8336 <jint/>
8337 <description>
8338 The number of platform threads waiting to own this monitor, or <code>0</code>
8339 if only virtual threads are waiting to be notified or no threads are waiting
8340 to be notified
8341 </description>
8342 </field>
8343 <field id="notify_waiters">
8344 <allocfieldbuf><jthread/></allocfieldbuf>
8345 <description>
8346 The <code>notify_waiter_count</code> platform threads waiting to be notified
8347 </description>
8348 </field>
8349 </typedef>
8350 <description>
8351 Get information about the object's monitor.
8352 The fields of the <functionlink id="jvmtiMonitorUsage"></functionlink> structure
8353 are filled in with information about usage of the monitor.
8354 <p/>
8355 When preview features are enabled, the object to query may be a value object.
8356 It is not possible to synchronize on a value object, so there is no monitor
8357 usage information to return. The fields of the returned
8358 <functionlink id="jvmtiMonitorUsage"></functionlink> structure will always
8359 be filled in with null values and zeros.
8360 <p/>
8361 <b> This function does not support getting information about an object's monitor
8362 when it is owned by a virtual thread. It also does not support returning a
8363 reference to virtual threads that are waiting to own a monitor or waiting to
8364 be notified.
8365 </b>
8366 <todo>
8367 Decide and then clarify suspend requirements.
8368 </todo>
8369 </description>
8370 <origin>jvmdi</origin>
8371 <capabilities>
8372 <required id="can_get_monitor_info"></required>
8373 </capabilities>
8374 <parameters>
8375 <param id="object">
8376 <jobject/>
8377 <description>
8378 The object to query.
8379 </description>
8380 </param>
10740 </capabilityfield>
10741 <capabilityfield id="can_generate_sampled_object_alloc_events" since="11">
10742 <description>
10743 Can generate sampled allocation events.
10744 If this capability is enabled then the heap sampling method
10745 <functionlink id="SetHeapSamplingInterval"></functionlink> can be
10746 called and <eventlink id="SampledObjectAlloc"></eventlink> events can be generated.
10747 </description>
10748 </capabilityfield>
10749 <capabilityfield id="can_support_virtual_threads" since="21">
10750 <description>
10751 Can support virtual threads.
10752 If this capability is enabled then the following functions can be called:
10753 <functionlink id="SuspendAllVirtualThreads"></functionlink>,
10754 <functionlink id="ResumeAllVirtualThreads"></functionlink>,
10755 and the following events can be enabled:
10756 <eventlink id="VirtualThreadStart"></eventlink>,
10757 <eventlink id="VirtualThreadEnd"></eventlink>.
10758 </description>
10759 </capabilityfield>
10760 <capabilityfield id="can_support_value_objects" since="28">
10761 <description>
10762 Can support value objects.
10763 When preview features are enabled and this capability is enabled, then
10764 events are sent for value objects when the following two events are enabled:
10765 <eventlink id="VMObjectAlloc"></eventlink>,
10766 <eventlink id="SampledObjectAlloc"></eventlink>.
10767 <b> can_support_value_objects is a preview API of the Java platform. </b>
10768 <i>Preview features may be removed in a future release, or upgraded to
10769 permanent features of the Java platform.</i>
10770 </description>
10771 </capabilityfield>
10772 </capabilitiestypedef>
10773
10774 <function id="GetPotentialCapabilities" jkernel="yes" phase="onload" num="140">
10775 <synopsis>Get Potential Capabilities</synopsis>
10776 <description>
10777 Returns via <paramlink id="capabilities_ptr"></paramlink> the <jvmti/>
10778 features that can potentially be possessed by this environment
10779 at this time.
10780 The returned capabilities differ from the complete set of capabilities
10781 implemented by the VM in two cases: another environment possesses
10782 capabilities that can only be possessed by one environment, or the
10783 current <functionlink id="GetPhase">phase</functionlink> is live,
10784 and certain capabilities can only be added during the <code>OnLoad</code> phase.
10785 The <functionlink id="AddCapabilities"></functionlink> function
10786 may be used to set any or all or these capabilities.
10787 Currently possessed capabilities are included.
10788 <p/>
10789 Typically this function is used in the <code>OnLoad</code> function.
10790 Some virtual machines may allow a limited set of capabilities to be
10791 added in the live phase.
14055 </description>
14056 </param>
14057 </parameters>
14058 </event>
14059
14060 <event label="VM Object Allocation"
14061 id="VMObjectAlloc" const="JVMTI_EVENT_VM_OBJECT_ALLOC" num="84">
14062 <description>
14063 Sent when a method causes the virtual machine to directly allocate an
14064 Object visible to Java programming language code.
14065 Generally object allocation should be detected by instrumenting
14066 the bytecodes of allocating methods.
14067 Object allocation generated in native code by JNI function
14068 calls should be detected using
14069 <internallink id="jniIntercept">JNI function interception</internallink>.
14070 Some methods might not have associated bytecodes and are not
14071 native methods, they instead are executed directly by the
14072 VM. These methods should send this event.
14073 Virtual machines which are incapable of bytecode instrumentation
14074 for some or all of their methods can send this event.
14075 <p/>
14076 When preview features are enabled and the capability <code>can_support_value_objects</code>
14077 is enabled, this event is sent for the value object allocations.
14078 <code>null</code> is passed for the <paramlink id="object"></paramlink> parameter in such cases.
14079 <p/>
14080 Note that the <internallink
14081 id="SampledObjectAlloc">SampledObjectAlloc</internallink>
14082 event is triggered on all Java object allocations, including those
14083 caused by bytecode method execution, JNI method execution, and
14084 directly by VM methods.
14085 <p/>
14086 Typical examples where this event might be sent:
14087 <ul>
14088 <li>Reflection -- for example, <code>java.lang.Class.newInstance()</code></li>
14089 <li>Methods not represented by bytecodes -- for example, VM intrinsics and
14090 J2ME preloaded classes</li>
14091 </ul>
14092 Cases where this event would not be generated:
14093 <ul>
14094 <li>Allocation due to bytecodes -- for example, the <code>new</code>
14095 and <code>newarray</code> VM instructions</li>
14096 <li>Allocation due to JNI function calls -- for example,
14097 <code>AllocObject</code></li>
14098 <li>Allocations during VM initialization</li>
14099 <li>VM internal objects</li>
14100 </ul>
14101 </description>
14102 <origin>new</origin>
14103 <capabilities>
14104 <required id="can_generate_vm_object_alloc_events"></required>
14105 <capability id="can_support_value_objects"></capability>
14106 </capabilities>
14107 <parameters>
14108 <param id="jni_env">
14109 <outptr>
14110 <struct>JNIEnv</struct>
14111 </outptr>
14112 <description>
14113 The JNI environment of the event (current) thread
14114 </description>
14115 </param>
14116 <param id="thread">
14117 <jthread/>
14118 <description>
14119 Thread allocating the object.
14120 </description>
14121 </param>
14122 <param id="object">
14123 <jobject/>
14124 <description>
14125 JNI local reference to the object that was allocated.
14126 Null when preview features are enabled, the capability <code>can_support_value_objects</code>
14127 is enabled, and the allocated object has no identity.
14128 </description>
14129 </param>
14130 <param id="object_klass">
14131 <jclass/>
14132 <description>
14133 JNI local reference to the class of the object.
14134 </description>
14135 </param>
14136 <param id="size">
14137 <jlong/>
14138 <description>
14139 Size of the object (in bytes). See <functionlink id="GetObjectSize"/>.
14140 </description>
14141 </param>
14142 </parameters>
14143 </event>
14144
14145 <event label="Sampled Object Allocation"
14146 id="SampledObjectAlloc" const="JVMTI_EVENT_SAMPLED_OBJECT_ALLOC" filtered="thread" num="86" since="11">
14147 <description>
14154 When the number of bytes exceeds the sampling interval, it will send another event.
14155 This implies that, on average, one object will be sampled every time a thread has
14156 allocated 512KB bytes since the last sample.
14157 <p/>
14158 Note that the sampler is pseudo-random: it will not sample every 512KB precisely.
14159 The goal of this is to ensure high quality sampling even if allocation is
14160 happening in a fixed pattern (i.e., the same set of objects are being allocated
14161 every 512KB).
14162 <p/>
14163 If another sampling interval is required, the user can call
14164 <functionlink id="SetHeapSamplingInterval"></functionlink> with a strictly positive integer value,
14165 representing the new sampling interval.
14166 <p/>
14167 This event is sent once the sampled allocation has been performed. It provides the object, stack trace
14168 of the allocation, the thread allocating, the size of allocation, and the object's class.
14169 <p/>
14170 A typical use case of this system is to determine where heap allocations originate.
14171 In conjunction with weak references and the function
14172 <functionlink id="GetStackTrace"></functionlink>, a user can track which objects were allocated from which
14173 stack trace, and which are still live during the execution of the program.
14174 <p/>
14175 When preview features are enabled and the capability <code>can_support_value_objects</code>
14176 is enabled, this event is sent for the allocated objects that have no identity.
14177 <code>null</code> is passed for the <paramlink id="object"></paramlink> parameter in such cases.
14178 </description>
14179 <origin>new</origin>
14180 <capabilities>
14181 <required id="can_generate_sampled_object_alloc_events"></required>
14182 <capability id="can_support_value_objects"></capability>
14183 </capabilities>
14184 <parameters>
14185 <param id="jni_env">
14186 <outptr>
14187 <struct>JNIEnv</struct>
14188 </outptr>
14189 <description>
14190 The JNI environment of the event (current) thread.
14191 </description>
14192 </param>
14193 <param id="thread">
14194 <jthread/>
14195 <description>
14196 Thread allocating the object.
14197 </description>
14198 </param>
14199 <param id="object">
14200 <jobject/>
14201 <description>
14202 JNI local reference to the object that was allocated.
14203 Null when preview features are enabled, the capability <code>can_support_value_objects</code>
14204 is enabled, and the allocated object has no identity.
14205 </description>
14206 </param>
14207 <param id="object_klass">
14208 <jclass/>
14209 <description>
14210 JNI local reference to the class of the object
14211 </description>
14212 </param>
14213 <param id="size">
14214 <jlong/>
14215 <description>
14216 Size of the object (in bytes). See <functionlink id="GetObjectSize"/>.
14217 </description>
14218 </param>
14219 </parameters>
14220 </event>
14221
14222 <event label="Object Free"
14223 id="ObjectFree" const="JVMTI_EVENT_OBJECT_FREE" num="83">
14224 <description>
14225 An Object Free event is sent when the garbage collector frees an object.
14226 Events are only sent for tagged objects--see
14227 <internallink id="Heap">heap functions</internallink>.
14228 <p/>
14229 When preview features are enabled, the Object Free event is only sent for tagged
14230 <externallink id="jni/functions.html#hasidentity">identity objects</externallink>.
14231 <b>The event is not sent for tagged value objects.</b>
14232 <p/>
14233 The event handler must not use JNI functions and
14234 must not use <jvmti/> functions except those which
14235 specifically allow such use (see the raw monitor, memory management,
14236 and environment local storage functions).
14237 </description>
14238 <origin>new</origin>
14239 <capabilities>
14240 <required id="can_generate_object_free_events"></required>
14241 </capabilities>
14242 <parameters>
14243 <param id="tag">
14244 <jlong/>
14245 <description>
14246 The freed object's tag
14247 </description>
14248 </param>
14249 </parameters>
14250 </event>
14251
14252 <event label="Garbage Collection Start"
15555 implementation may choose to not call the Agent_OnUnload function
15556 if the Agent_OnAttach/Agent_OnAttach_L function reported an error.
15557 </change>
15558 <change date="8 June 2021" version="17.0.0">
15559 Minor update to deprecate Heap functions 1.0.
15560 </change>
15561 <change date="27 April 2022" version="19.0.0">
15562 Support for virtual threads (Preview):
15563 Add new capability: can_support_virtual_threads.
15564 Add new functions: SuspendAllVirtualThreads, ResumeAllVirtualThreads.
15565 Add new event types: JVMTI_EVENT_VIRTUAL_THREAD_START, JVMTI_EVENT_VIRTUAL_THREAD_END.
15566 Add new error code: JVMTI_ERROR_UNSUPPORTED_OPERATION.
15567 </change>
15568 <change date="7 June 2023" version="21.0.0">
15569 Virtual threads finalized to be a permanent feature.
15570 Agent start-up in the live phase now specified to print a warning.
15571 </change>
15572 <change date="10 January 2025" version="25.0.0">
15573 Add new function ClearAllFramePops. Needed to speedup debugger single stepping.
15574 </change>
15575 <change date="30 June 2026" version="28.0.0">
15576 Support for value objects (Preview):
15577 Add new capability: can_support_value_objects which enables
15578 the following events for value objects:
15579 JVMTI_EVENT_VM_OBJECT_ALLOC, JVMTI_EVENT_SAMPLED_OBJECT_ALLOC.
15580 </change>
15581 </changehistory>
15582
15583 </specification>
15584 <!-- Keep this comment at the end of the file
15585 Local variables:
15586 mode: sgml
15587 sgml-omittag:t
15588 sgml-shorttag:t
15589 sgml-namecase-general:t
15590 sgml-general-insert-case:lower
15591 sgml-minimize-attributes:nil
15592 sgml-always-quote-attributes:t
15593 sgml-indent-step:2
15594 sgml-indent-data:t
15595 sgml-parent-document:nil
15596 sgml-exposed-tags:nil
15597 sgml-local-catalogs:nil
15598 sgml-local-ecat-files:nil
15599 End:
15600 -->
|