Internal change

RELNOTES=Redocumented ClosingFuture functions to make it clearer that Closeables begin closing *after* completion of the Future or ValueAndCloser that the pipeline emits, rather than before. PiperOrigin-RevId: 347929525
google · Dec 17, 2020 · c8d0536 · c8d0536
1 parent 2b55799
commit c8d0536
Show file tree

Hide file tree

Showing 2 changed files with 22 additions and 10 deletions.
diff --git a/android/guava/src/com/google/common/util/concurrent/ClosingFuture.java b/android/guava/src/com/google/common/util/concurrent/ClosingFuture.java
@@ -137,8 +137,9 @@
  * <h4>Automatically closing</h4>
  *
  * You can extract a {@link Future} that represents the result of the last step in the pipeline by
- * calling {@link #finishToFuture()}. When that final {@link Future} is done, all objects captured
- * by all steps in the pipeline will be closed.
+ * calling {@link #finishToFuture()}. All objects the pipeline has captured for closing will begin
+ * to be closed asynchronously <b>after</b> the returned {@code Future} is done: the future
+ * completes before closing starts, rather than once it has finished.
  *
  * <pre>{@code
  * FluentFuture<UserName> userName =
@@ -983,9 +984,14 @@ public String toString() {
   }
 
   /**
-   * Marks this step as the last step in the {@code ClosingFuture} pipeline. When the returned
-   * {@link Future} is done, all objects captured for closing during the pipeline's computation will
-   * be closed.
+   * Marks this step as the last step in the {@code ClosingFuture} pipeline.
+   *
+   * <p>The returned {@link Future} is completed when the pipeline's computation completes, or when
+   * the pipeline is cancelled.
+   *
+   * <p>All objects the pipeline has captured for closing will begin to be closed asynchronously
+   * <b>after</b> the returned {@code Future} is done: the future completes before closing starts,
+   * rather than once it has finished.
    *
    * <p>After calling this method, you may not call {@link
    * #finishToValueAndCloser(ValueAndCloserConsumer, Executor)}, this method, or any other

diff --git a/guava/src/com/google/common/util/concurrent/ClosingFuture.java b/guava/src/com/google/common/util/concurrent/ClosingFuture.java
@@ -136,8 +136,9 @@
  * <h4>Automatically closing</h4>
  *
  * You can extract a {@link Future} that represents the result of the last step in the pipeline by
- * calling {@link #finishToFuture()}. When that final {@link Future} is done, all objects captured
- * by all steps in the pipeline will be closed.
+ * calling {@link #finishToFuture()}. All objects the pipeline has captured for closing will begin
+ * to be closed asynchronously <b>after</b> the returned {@code Future} is done: the future
+ * completes before closing starts, rather than once it has finished.
  *
  * <pre>{@code
  * FluentFuture<UserName> userName =
@@ -983,9 +984,14 @@ public String toString() {
   }
 
   /**
-   * Marks this step as the last step in the {@code ClosingFuture} pipeline. When the returned
-   * {@link Future} is done, all objects captured for closing during the pipeline's computation will
-   * be closed.
+   * Marks this step as the last step in the {@code ClosingFuture} pipeline.
+   *
+   * <p>The returned {@link Future} is completed when the pipeline's computation completes, or when
+   * the pipeline is cancelled.
+   *
+   * <p>All objects the pipeline has captured for closing will begin to be closed asynchronously
+   * <b>after</b> the returned {@code Future} is done: the future completes before closing starts,
+   * rather than once it has finished.
    *
    * <p>After calling this method, you may not call {@link
    * #finishToValueAndCloser(ValueAndCloserConsumer, Executor)}, this method, or any other