changeset 56613:02db50f278f9

8220238: Enhancing j.l.Runtime/System::gc specification with an explicit 'no guarantee' statement Reviewed-by: shade, dholmes, mchung, plevart
author rriggs
date Wed, 05 Jun 2019 10:21:02 -0400
parents 9775d05d69c8
children 9b392b044f64
files src/java.base/share/classes/java/lang/Runtime.java src/java.base/share/classes/java/lang/System.java
diffstat 2 files changed, 24 insertions(+), 16 deletions(-) [+]
line wrap: on
line diff
--- a/src/java.base/share/classes/java/lang/Runtime.java	Wed Jun 05 15:19:13 2019 +0200
+++ b/src/java.base/share/classes/java/lang/Runtime.java	Wed Jun 05 10:21:02 2019 -0400
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1995, 2018, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1995, 2019, 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
@@ -639,15 +639,20 @@
     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.
+     * <p>
+     * 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.
+     * When control returns from the method call, the Java Virtual Machine
+     * has made a best effort to reclaim space from all unused objects.
+     * 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.
      * <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>
--- a/src/java.base/share/classes/java/lang/System.java	Wed Jun 05 15:19:13 2019 +0200
+++ b/src/java.base/share/classes/java/lang/System.java	Wed Jun 05 10:21:02 2019 -0400
@@ -1782,14 +1782,17 @@
     }
 
     /**
-     * Runs the garbage collector.
-     *
-     * Calling the {@code gc} 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 Java Virtual
-     * Machine has made a best effort to reclaim space from all discarded
-     * objects.
+     * Runs the garbage collector in the Java Virtual Machine.
+     * <p>
+     * Calling the {@code gc} 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.
+     * When control returns from the method call, the Java Virtual Machine
+     * has made a best effort to reclaim space from all unused objects.
+     * 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.
      * <p>
      * The call {@code System.gc()} is effectively equivalent to the
      * call: