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= 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