< prev index next > src/hotspot/share/prims/jvmti.xml
Print this page
<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="jvmti.xsl"?>
<!--
- Copyright (c) 2002, 2025, Oracle and/or its affiliates. All rights reserved.
+ Copyright (c) 2002, 2026, Oracle and/or its affiliates. All rights reserved.
DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
This code is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License version 2 only, as
published by the Free Software Foundation.
</function>
<function id="ForceEarlyReturnVoid" num="86" since="1.1">
<synopsis>Force Early Return - Void</synopsis>
<description>
- This function can be used to return from a method with no result type.
- That is, the called method must be declared <code>void</code>.
+ This function can be used to return from a method with a return type
+ of <code>void</code>.
+ A constructor is a special method named <code><init></code> with
+ a return type of <code>void</code>. A class initializer is a special
+ method named named <code><clinit></code> with a return type of
+ <code>void</code>.
+ <p/>
+ When preview features are enabled, this function can not be used to return
+ early from the constructor of a value class.
</description>
<origin>new</origin>
<capabilities>
<required id="can_force_early_return"></required>
</capabilities>
</param>
</parameters>
<errors>
<error id="JVMTI_ERROR_OPAQUE_FRAME">
The implementation is unable to force the current frame to return
- (e.g. current frame is executing a native method).
+ (e.g. current frame is executing a native method or if preview features
+ are enabled, the current frame is the constructor for a value class)
</error>
<error id="JVMTI_ERROR_TYPE_MISMATCH">
The called method has a result type.
</error>
<error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
Tags are <code>jlong</code> values which can be used
simply to mark an object or to store a pointer to more detailed
information. Objects which have not been tagged have a
tag of zero.
Setting a tag to zero makes the object untagged.
+ <p/>
+ If the <eventlink id="ObjectFree"/> event is enabled then an Object Free
+ event is sent for tagged objects when the garbage collector frees the object.
+ When preview features are enabled, the Object Free event is only sent for tagged
+ <externallink id="jni/functions.html#hasidentity">identity objects</externallink>.
+ <b>The event is not sent for tagged values objects.</b>
</intro>
<intro id="heapCallbacks" label="Heap Callback Functions">
Heap functions which iterate through the heap and recursively
follow object references use agent supplied callback functions
<synopsis>Get Local Variable - Object</synopsis>
<description>
This function can be used to retrieve the value of a local
variable whose type is <code>Object</code> or a subclass of <code>Object</code>.
<p/>
+ When preview features are enabled, if the local is the "<code>this</code>"
+ object and "<code>this</code>" is a value object under construction, the
+ function retrieves a snapshot of the "<code>this</code>" object representing
+ the value object's state at the point the snapshot is taken.
+ <p/>
The specified thread must be suspended or must be the current thread.
</description>
<origin>jvmdi</origin>
<capabilities>
<required id="can_access_local_variables"></required>
</param>
<param id="value_ptr">
<outptr><jobject/></outptr>
<description>
On return, points to the variable's value.
+ When preview features are enabled, if the local is the "<code>this</code>"
+ object and "<code>this</code>" is a value object under construction,
+ <code>value_ptr</code> will point to a snapshot of the "<code>this</code>"
+ object representing the value object's state at the point the snapshot
+ is taken.
</description>
</param>
</parameters>
<errors>
<error id="JVMTI_ERROR_INVALID_SLOT">
variable at slot 0 (the "<code>this</code>" object) from non-static
frames. This function can retrieve the "<code>this</code>" object from
native method frames, whereas <code>GetLocalObject()</code> would
return <code>JVMTI_ERROR_OPAQUE_FRAME</code> in those cases.
<p/>
+ When preview features are enabled and the "<code>this</code>" object is
+ a value object under construction, the function retrieves a snapshot of the
+ "<code>this</code>" object that represents the value object's state at
+ the point the snapshot is taken.
+ <p/>
The specified thread must be suspended or must be the current thread.
</description>
<origin>new</origin>
<capabilities>
<required id="can_access_local_variables"></required>
</param>
<param id="value_ptr">
<outptr><jobject/></outptr>
<description>
On return, points to the variable's value.
+ When preview features are enabled, and the "<code>this</code>" object is
+ a value object under construction, <code>value_ptr</code> will point to
+ a snapshot of the "<code>this</code>" object representing the value
+ object's state at the point the snapshot is taken.
</description>
</param>
</parameters>
<errors>
<error id="JVMTI_ERROR_INVALID_SLOT">
</function>
<function id="GetClassModifiers" phase="start" num="51">
<synopsis>Get Class Modifiers</synopsis>
<description>
- For the class indicated by <code>klass</code>, return the access
- flags
- via <code>modifiers_ptr</code>.
- Access flags are defined in <vmspec chapter="4"/>.
- <p/>
- If the class is an array class, then its public, private, and protected
- modifiers are the same as those of its component type. For arrays of
+ For the class indicated by <code>klass</code>, return the Java language
+ modifiers and class/interface properties of the corresponding
+ <code>java.lang.Class</code> object, via <code>modifiers_ptr</code>.
+ <p/>
+ The modifiers are encoded as a mask of access-flag bit values defined in
+ <vmspec chapter="4"/>. The returned value is not necessarily the value of the
+ access_flags item in the class file of <code>klass</code>.
+ In particular, for member, local, or anonymous classes and interfaces, the result
+ may include modifiers represented by access flags from the <code>InnerClasses</code>
+ attribute, such as <code>ACC_STATIC</code>.
+ <p/>
+ The modifiers include, as applicable, the Java Virtual Machine constants for
+ public, private, protected, final, static, abstract, and interface, as well as
+ access-flag bit values for other class/interface properties encoded in the
+ result of invoking <code>java.lang.Class.getModifiers()</code> on the
+ corresponding <code>java.lang.Class</code> object.
+ <p/>
+ If <code>klass</code> is an array class, then its public, private, and
+ protected modifiers are the same as those of its component type. For arrays of
primitives, this component type is represented by one of the primitive
- classes (for example, <code>java.lang.Integer.TYPE</code>).
+ classes, such as <code>java.lang.Integer.TYPE</code>. For array classes, the
+ abstract and final modifiers are set, and the interface modifier is not set.
<p/>
- If the class is a primitive class, its public modifier is always true,
- and its protected and private modifiers are always false.
+ If <code>klass</code> is a primitive type or void, then its public, abstract,
+ and final modifiers are always set, and its protected, private, and interface
+ modifiers are never set.
<p/>
- If the class is an array class or a primitive class then its final
- modifier is always true and its interface modifier is always false.
- The values of its other modifiers are not determined by this specification.
-
+ When preview features are enabled, the <code>ACC_IDENTITY</code> access flag
+ is set if and only if <code>klass</code> is an identity class or an array class.
+ <p/>
+ When preview features are disabled, the <code>ACC_SUPER</code> access flag may be
+ set only if <code>klass</code> is not a primitive type or void. The flag has no
+ effective meaning.
</description>
<origin>jvmdi</origin>
<capabilities>
</capabilities>
<parameters>
</description>
</param>
<param id="modifiers_ptr">
<outptr><jint/></outptr>
<description>
- On return, points to the current access flags of this class.
+ On return, points to the modifiers of this class.
</description>
</param>
</parameters>
<errors>
<description>
Get information about the object's monitor.
The fields of the <functionlink id="jvmtiMonitorUsage"></functionlink> structure
are filled in with information about usage of the monitor.
<p/>
+ When preview features are enabled, the object to query may be a value object.
+ It is not possible to synchronize on a value object, so there is no monitor
+ usage information to return. The fields of the returned
+ <functionlink id="jvmtiMonitorUsage"></functionlink> structure will always
+ be filled in with null values and zeros.
+ <p/>
<b> This function does not support getting information about an object's monitor
when it is owned by a virtual thread. It also does not support returning a
reference to virtual threads that are waiting to own a monitor or waiting to
be notified.
</b>
and the following events can be enabled:
<eventlink id="VirtualThreadStart"></eventlink>,
<eventlink id="VirtualThreadEnd"></eventlink>.
</description>
</capabilityfield>
+ <capabilityfield id="can_support_value_objects" since="28">
+ <description>
+ Can support value objects.
+ When preview features are enabled and this capability is enabled, then
+ events are sent for value objects when the following two events are enabled:
+ <eventlink id="VMObjectAlloc"></eventlink>,
+ <eventlink id="SampledObjectAlloc"></eventlink>.
+ <b> can_support_value_objects is a preview API of the Java platform. </b>
+ <i>Preview features may be removed in a future release, or upgraded to
+ permanent features of the Java platform.</i>
+ </description>
+ </capabilityfield>
</capabilitiestypedef>
<function id="GetPotentialCapabilities" jkernel="yes" phase="onload" num="140">
<synopsis>Get Potential Capabilities</synopsis>
<description>
Some methods might not have associated bytecodes and are not
native methods, they instead are executed directly by the
VM. These methods should send this event.
Virtual machines which are incapable of bytecode instrumentation
for some or all of their methods can send this event.
-
+ <p/>
+ When preview features are enabled and the capability <code>can_support_value_objects</code>
+ is enabled, this event is sent for the value object allocations.
+ <code>null</code> is passed for the <paramlink id="object"></paramlink> parameter in such cases.
+ <p/>
Note that the <internallink
id="SampledObjectAlloc">SampledObjectAlloc</internallink>
event is triggered on all Java object allocations, including those
caused by bytecode method execution, JNI method execution, and
directly by VM methods.
</ul>
</description>
<origin>new</origin>
<capabilities>
<required id="can_generate_vm_object_alloc_events"></required>
+ <capability id="can_support_value_objects"></capability>
</capabilities>
<parameters>
<param id="jni_env">
<outptr>
<struct>JNIEnv</struct>
</param>
<param id="object">
<jobject/>
<description>
JNI local reference to the object that was allocated.
+ Null when preview features are enabled, the capability <code>can_support_value_objects</code>
+ is enabled, and the allocated object has no identity.
</description>
</param>
<param id="object_klass">
<jclass/>
<description>
<p/>
A typical use case of this system is to determine where heap allocations originate.
In conjunction with weak references and the function
<functionlink id="GetStackTrace"></functionlink>, a user can track which objects were allocated from which
stack trace, and which are still live during the execution of the program.
+ <p/>
+ When preview features are enabled and the capability <code>can_support_value_objects</code>
+ is enabled, this event is sent for the allocated objects that have no identity.
+ <code>null</code> is passed for the <paramlink id="object"></paramlink> parameter in such cases.
</description>
<origin>new</origin>
<capabilities>
<required id="can_generate_sampled_object_alloc_events"></required>
+ <capability id="can_support_value_objects"></capability>
</capabilities>
<parameters>
<param id="jni_env">
<outptr>
<struct>JNIEnv</struct>
</param>
<param id="object">
<jobject/>
<description>
JNI local reference to the object that was allocated.
+ Null when preview features are enabled, the capability <code>can_support_value_objects</code>
+ is enabled, and the allocated object has no identity.
</description>
</param>
<param id="object_klass">
<jclass/>
<description>
<description>
An Object Free event is sent when the garbage collector frees an object.
Events are only sent for tagged objects--see
<internallink id="Heap">heap functions</internallink>.
<p/>
+ When preview features are enabled, the Object Free event is only sent for tagged
+ <externallink id="jni/functions.html#hasidentity">identity objects</externallink>.
+ <b>The event is not sent for tagged values objects.</b>
+ <p/>
The event handler must not use JNI functions and
must not use <jvmti/> functions except those which
specifically allow such use (see the raw monitor, memory management,
and environment local storage functions).
</description>
Agent start-up in the live phase now specified to print a warning.
</change>
<change date="10 January 2025" version="25.0.0">
Add new function ClearAllFramePops. Needed to speedup debugger single stepping.
</change>
+ <change date="30 June 2026" version="28.0.0">
+ Support for value objects (Preview):
+ Add new capability: can_support_value_objects which enables
+ the following events for value objects:
+ JVMTI_EVENT_VM_OBJECT_ALLOC, JVMTI_EVENT_SAMPLED_OBJECT_ALLOC.
+ </change>
</changehistory>
</specification>
<!-- Keep this comment at the end of the file
Local variables:
< prev index next >