src/java.base/share/classes/java/lang/Runtime.java

rev 55032 : 8220238: Enhancing j.l.Runtime/System::gc specification with an explicit 'no guarantee' statement
Reviewed-by: tbd

@@ -637,19 +637,22 @@
      * @since 1.4
      */
     public native long maxMemory();
 
     /**
-     * Runs the garbage collector.
-     * Calling this method suggests that the Java virtual machine expend
-     * effort toward recycling unused objects in order to make the memory
-     * they currently occupy available for quick reuse. When control
-     * returns from the method call, the virtual machine has made
-     * its best effort to recycle all discarded objects.
+     * Runs the garbage collector in the Java Virtual Machine.
+     *
+     * Calling this method suggests that the Java Virtual Machine
+     * expend effort toward recycling unused objects in order to
+     * make the memory they currently occupy available for reuse
+     * by the Java Virtual Machine.
+     * 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.
      * <p>
      * The name {@code gc} stands for "garbage
-     * collector". The virtual machine performs this recycling
+     * collector". The Java Virtual Machine performs this recycling
      * process automatically as needed, in a separate thread, even if the
      * {@code gc} method is not invoked explicitly.
      * <p>
      * The method {@link System#gc()} is the conventional and convenient
      * means of invoking this method.