src/hotspot/share/prims/jvmti.xml

*** 1,9 ***
  <?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.
   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.
--- 1,9 ---
  <?xml version="1.0" encoding="UTF-8"?>
  <?xml-stylesheet type="text/xsl" href="jvmti.xsl"?>
  <!--
!  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.

*** 5886,10 ***
--- 5886,15 ---
          </param>
          <param id="value_ptr">
            <outptr><jobject/></outptr>
              <description>
                On return, points to the variable's value.
+               When preview features are enabled, if the requested local is the
+               "<code>this</code>" object, and "<code>this</code>" is a value
+               object under construction, the value_ptr is set to a snapshot
+               of the "<code>this</code>" object that represents the value
+               object's state at the point the snapshot is taken.
              </description>
          </param>
        </parameters>
        <errors>
          <error id="JVMTI_ERROR_INVALID_SLOT">

*** 5939,10 ***
--- 5944,14 ---
          </param>
          <param id="value_ptr">
            <outptr><jobject/></outptr>
              <description>
                On return, points to the variable's value.
+               When preview features are enabled, and the local instance is a value
+               object under construction, the value_ptr is set to a snapshot
+               of the "<code>this</code>" object that represents the value
+               object's state at the point the snapshot is taken.
              </description>
          </param>
        </parameters>
        <errors>
          <error id="JVMTI_ERROR_INVALID_SLOT">

*** 13986,10 ***
--- 13995,12 ---
        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.
+       When preview features are enabled and the allocated object has no identity,
+       <code>null</code> is passed for the <paramlink id="object"></paramlink> parameter.
  
        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

*** 14032,10 ***
--- 14043,11 ---
        </param>
        <param id="object">
          <jobject/>
            <description>
              JNI local reference to the object that was allocated.
+             Null when preview features are enabled and the allocated object has no identity.
            </description>
        </param>
        <param id="object_klass">
          <jclass/>
            <description>

*** 14078,10 ***
--- 14090,13 ---
        <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.
+       When preview features are enabled and the allocated object has no identity,
+       <code>null</code> is passed for the <paramlink id="object"></paramlink> parameter.
+       Note that weak references support identity objects only.
      </description>
      <origin>new</origin>
      <capabilities>
        <required id="can_generate_sampled_object_alloc_events"></required>
      </capabilities>

*** 14102,10 ***
--- 14117,11 ---
        </param>
        <param id="object">
          <jobject/>
          <description>
            JNI local reference to the object that was allocated.
+           Null when preview features are enabled and the allocated object has no identity.
          </description>
        </param>
        <param id="object_klass">
          <jclass/>
          <description>

*** 14130,10 ***
--- 14146,11 ---
        <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).
+       When preview features are enabled, this event does not support value object allocations.
      </description>
      <origin>new</origin>
      <capabilities>
        <required id="can_generate_object_free_events"></required>
      </capabilities>