JDK-8268242 : Deprecate JVM TI Heap functions 1.0
  • Type: CSR
  • Component: hotspot
  • Sub-Component: jvmti
  • Priority: P3
  • Status: Closed
  • Resolution: Approved
  • Fix Versions: 17
  • Submitted: 2021-06-04
  • Updated: 2021-11-10
  • Resolved: 2021-06-07
Related Reports
CSR :  
JDK-8268241 - Deprecate JVM TI Heap functions 1.0
Relates :  
JDK-8003551 - Move Signers out to the JDK
Description
Summary
-------

Deprecate the JVM TI "Heap (1.0)" functions. Add wording to the JVM TI spec to say that the functions are deprecated and will be "degraded" in a future release. These functions are obsolete and were superseded by a newer set of Heap functions in JVM TI 1.2 (Java 6).


Problem
-------

The JVM TI Heap functions reflect the requirements of tool vendors during JSR-163. They pre-date concurrent collectors, the built-in heap dump support, and JFR. They are a maintenance burden and there is little evidence that they are used by modern tools (they involve stop-the-world operations and so are not suitable for production systems).


Solution
--------

Deprecate the following JVM TI functions 

- IterateOverObjectsReachableFromObject
- IterateOverReachableObjects
- IterateOverHeap
- IterateOverInstancesOfClass

The "Heap 1.0" section of the JVM TI spec has existing wording in bold to say that the functions have been superseded. The proposal is to change this to say that the functions are deprecated and will be degraded in a future release.

A release note is planned. The release note will detail how to use -Xlog:jvmti=trace and -XX:TraceJVMTI=<desc> to identify any residual usages of these functions.

A future CSR will likely degrade these functions so that they return an error to indicate that they are no longer implemented/supported. We also plan to re-examine the newer Heap functions with a view to deprecate them in the future too (this requires a bit more work to understand if there is any real usage, also some adjustments to the JDWP and JDI specs).



Specification
-------------

Replace this sentence:
"These functions and data types were introduced in the original JVM TI
version 1.0 and have been superseded by more powerful and flexible
versions which:"

with:

"These functions and data types were introduced in the original JVM TI
version 1.0. They are deprecated and will be changed to return an error
in a future release. They were superseded in JVM TI version 1.2 (Java SE
6) by more powerful and flexible versions that:" 


The updated JVM TI spec section can be found here:

  http://cr.openjdk.java.net/~sspitsyn/webrevs/2021/jvmti-deprecate-heap-funcs.1/jvmti.html#Heap_1_0
Comments
Moving to Approved.
07-06-2021
Thanks, Alan. I'm finalizing it again.
07-06-2021
I've updated the CSR to say that the release note will show how to enable tracing so that any residual usages of these JVM TI functions can be identified, e.g. -Xlog:jvmti=trace -XX:TraceJVMTI=IterateOverHeap` is one way to get trace output when IterateOverHeap is used.
05-06-2021
Moving to Provisional, not Approved. Is there some mechanism to generate a warning / notification if this functionality is used?
04-06-2021
I've updated the Summary, Problem, and Solutions sections to make it a bit clear what this CSR is about and to put more context on it. A release note is planned.
04-06-2021