Summary

Clarify in the spec of System::gc and Runtime::gc that there is no guarantee on Reference objects being processed, enqueued and cleared.

Problem

System::gc does not guarantee reclaiming memory of any particular number of unused objects. There is also no guarantee of change of reachability be detected. The specification should be clarified.

Solution

Clarify in the javadoc of System::gc and Runtime::gc that there is no guarantee that it will detect that the reachability of any objects has changed or any Reference objects will be enqueued and cleared.

Specification

Clarify in the javadoc of System::gc and Runtime::gc as follows:

--- a/src/java.base/share/classes/java/lang/Runtime.java
+++ b/src/java.base/share/classes/java/lang/Runtime.java
@@ -655,6 +655,10 @@ public class Runtime {
      * There is no guarantee that this effort will recycle any particular
      * number of unused objects, reclaim any particular amount of space, or
      * complete at any particular time, if at all, before the method returns or ever.
+     * There is also no guarantee that this effort will determine
+     * the change of reachability in any particular number of objects,
+     * or that any particular number of {@link java.lang.ref.Reference Reference}
+     * objects will be cleared and enqueued.
      * <p>
      * The name {@code gc} stands for "garbage
      * collector". The Java Virtual Machine performs this recycling
diff --git a/src/java.base/share/classes/java/lang/System.java b/src/java.base/share/classes/java/lang/System.java
index de8122dc074..bfffe06a62b 100644
--- a/src/java.base/share/classes/java/lang/System.java
+++ b/src/java.base/share/classes/java/lang/System.java
@@ -1836,6 +1836,11 @@ public final class System {
      * There is no guarantee that this effort will recycle any particular
      * number of unused objects, reclaim any particular amount of space, or
      * complete at any particular time, if at all, before the method returns or ever.
+     * There is also no guarantee that this effort will determine
+     * the change of reachability in any particular number of objects,
+     * or that any particular number of {@link java.lang.ref.Reference Reference}
+     * objects will be cleared and enqueued.
+     *
      * <p>
      * The call {@code System.gc()} is effectively equivalent to the
      * call: