From c8d05367c2862ac74781a62061b4fd55e98ffda9 Mon Sep 17 00:00:00 2001
From: yorick <yorick@google.com>
Date: Wed, 16 Dec 2020 17:31:18 -0800
Subject: [PATCH] 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
---
 .../common/util/concurrent/ClosingFuture.java    | 16 +++++++++++-----
 .../common/util/concurrent/ClosingFuture.java    | 16 +++++++++++-----
 2 files changed, 22 insertions(+), 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
index 5576d09d800f..5969c4ff7d2e 100644
--- 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
index 7aca5b92d4e8..09767dc00fd4 100644
--- 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