001/* 002 * Copyright (C) 2017 The Guava Authors 003 * 004 * Licensed under the Apache License, Version 2.0 (the "License"); 005 * you may not use this file except in compliance with the License. 006 * You may obtain a copy of the License at 007 * 008 * http://www.apache.org/licenses/LICENSE-2.0 009 * 010 * Unless required by applicable law or agreed to in writing, software 011 * distributed under the License is distributed on an "AS IS" BASIS, 012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 013 * See the License for the specific language governing permissions and 014 * limitations under the License. 015 */ 016 017package com.google.common.util.concurrent; 018 019import static com.google.common.base.Functions.constant; 020import static com.google.common.base.MoreObjects.toStringHelper; 021import static com.google.common.base.Preconditions.checkArgument; 022import static com.google.common.base.Preconditions.checkNotNull; 023import static com.google.common.base.Preconditions.checkState; 024import static com.google.common.collect.Lists.asList; 025import static com.google.common.util.concurrent.ClosingFuture.State.CLOSED; 026import static com.google.common.util.concurrent.ClosingFuture.State.CLOSING; 027import static com.google.common.util.concurrent.ClosingFuture.State.OPEN; 028import static com.google.common.util.concurrent.ClosingFuture.State.SUBSUMED; 029import static com.google.common.util.concurrent.ClosingFuture.State.WILL_CLOSE; 030import static com.google.common.util.concurrent.ClosingFuture.State.WILL_CREATE_VALUE_AND_CLOSER; 031import static com.google.common.util.concurrent.Futures.getDone; 032import static com.google.common.util.concurrent.Futures.immediateFuture; 033import static com.google.common.util.concurrent.Futures.nonCancellationPropagating; 034import static com.google.common.util.concurrent.MoreExecutors.directExecutor; 035import static com.google.common.util.concurrent.Platform.restoreInterruptIfIsInterruptedException; 036import static java.util.logging.Level.FINER; 037import static java.util.logging.Level.SEVERE; 038import static java.util.logging.Level.WARNING; 039 040import com.google.common.annotations.J2ktIncompatible; 041import com.google.common.annotations.VisibleForTesting; 042import com.google.common.collect.FluentIterable; 043import com.google.common.collect.ImmutableList; 044import com.google.common.util.concurrent.ClosingFuture.Combiner.AsyncCombiningCallable; 045import com.google.common.util.concurrent.ClosingFuture.Combiner.CombiningCallable; 046import com.google.common.util.concurrent.Futures.FutureCombiner; 047import com.google.errorprone.annotations.CanIgnoreReturnValue; 048import com.google.errorprone.annotations.DoNotMock; 049import com.google.j2objc.annotations.RetainedWith; 050import java.io.Closeable; 051import java.util.IdentityHashMap; 052import java.util.Map; 053import java.util.concurrent.Callable; 054import java.util.concurrent.CancellationException; 055import java.util.concurrent.CountDownLatch; 056import java.util.concurrent.ExecutionException; 057import java.util.concurrent.Executor; 058import java.util.concurrent.Future; 059import java.util.concurrent.RejectedExecutionException; 060import java.util.concurrent.atomic.AtomicReference; 061import javax.annotation.CheckForNull; 062import org.checkerframework.checker.nullness.qual.Nullable; 063 064/** 065 * A step in a pipeline of an asynchronous computation. When the last step in the computation is 066 * complete, some objects captured during the computation are closed. 067 * 068 * <p>A pipeline of {@code ClosingFuture}s is a tree of steps. Each step represents either an 069 * asynchronously-computed intermediate value, or else an exception that indicates the failure or 070 * cancellation of the operation so far. The only way to extract the value or exception from a step 071 * is by declaring that step to be the last step of the pipeline. Nevertheless, we refer to the 072 * "value" of a successful step or the "result" (value or exception) of any step. 073 * 074 * <ol> 075 * <li>A pipeline starts at its leaf step (or steps), which is created from either a callable 076 * block or a {@link ListenableFuture}. 077 * <li>Each other step is derived from one or more input steps. At each step, zero or more objects 078 * can be captured for later closing. 079 * <li>There is one last step (the root of the tree), from which you can extract the final result 080 * of the computation. After that result is available (or the computation fails), all objects 081 * captured by any of the steps in the pipeline are closed. 082 * </ol> 083 * 084 * <h3>Starting a pipeline</h3> 085 * 086 * Start a {@code ClosingFuture} pipeline {@linkplain #submit(ClosingCallable, Executor) from a 087 * callable block} that may capture objects for later closing. To start a pipeline from a {@link 088 * ListenableFuture} that doesn't create resources that should be closed later, you can use {@link 089 * #from(ListenableFuture)} instead. 090 * 091 * <h3>Derived steps</h3> 092 * 093 * A {@code ClosingFuture} step can be derived from one or more input {@code ClosingFuture} steps in 094 * ways similar to {@link FluentFuture}s: 095 * 096 * <ul> 097 * <li>by transforming the value from a successful input step, 098 * <li>by catching the exception from a failed input step, or 099 * <li>by combining the results of several input steps. 100 * </ul> 101 * 102 * Each derivation can capture the next value or any intermediate objects for later closing. 103 * 104 * <p>A step can be the input to at most one derived step. Once you transform its value, catch its 105 * exception, or combine it with others, you cannot do anything else with it, including declare it 106 * to be the last step of the pipeline. 107 * 108 * <h4>Transforming</h4> 109 * 110 * To derive the next step by asynchronously applying a function to an input step's value, call 111 * {@link #transform(ClosingFunction, Executor)} or {@link #transformAsync(AsyncClosingFunction, 112 * Executor)} on the input step. 113 * 114 * <h4>Catching</h4> 115 * 116 * To derive the next step from a failed input step, call {@link #catching(Class, ClosingFunction, 117 * Executor)} or {@link #catchingAsync(Class, AsyncClosingFunction, Executor)} on the input step. 118 * 119 * <h4>Combining</h4> 120 * 121 * To derive a {@code ClosingFuture} from two or more input steps, pass the input steps to {@link 122 * #whenAllComplete(Iterable)} or {@link #whenAllSucceed(Iterable)} or its overloads. 123 * 124 * <h3>Cancelling</h3> 125 * 126 * Any step in a pipeline can be {@linkplain #cancel(boolean) cancelled}, even after another step 127 * has been derived, with the same semantics as cancelling a {@link Future}. In addition, a 128 * successfully cancelled step will immediately start closing all objects captured for later closing 129 * by it and by its input steps. 130 * 131 * <h3>Ending a pipeline</h3> 132 * 133 * Each {@code ClosingFuture} pipeline must be ended. To end a pipeline, decide whether you want to 134 * close the captured objects automatically or manually. 135 * 136 * <h4>Automatically closing</h4> 137 * 138 * You can extract a {@link Future} that represents the result of the last step in the pipeline by 139 * calling {@link #finishToFuture()}. All objects the pipeline has captured for closing will begin 140 * to be closed asynchronously <b>after</b> the returned {@code Future} is done: the future 141 * completes before closing starts, rather than once it has finished. 142 * 143 * <pre>{@code 144 * FluentFuture<UserName> userName = 145 * ClosingFuture.submit( 146 * closer -> closer.eventuallyClose(database.newTransaction(), closingExecutor), 147 * executor) 148 * .transformAsync((closer, transaction) -> transaction.queryClosingFuture("..."), executor) 149 * .transform((closer, result) -> result.get("userName"), directExecutor()) 150 * .catching(DBException.class, e -> "no user", directExecutor()) 151 * .finishToFuture(); 152 * }</pre> 153 * 154 * In this example, when the {@code userName} {@link Future} is done, the transaction and the query 155 * result cursor will both be closed, even if the operation is cancelled or fails. 156 * 157 * <h4>Manually closing</h4> 158 * 159 * If you want to close the captured objects manually, after you've used the final result, call 160 * {@link #finishToValueAndCloser(ValueAndCloserConsumer, Executor)} to get an object that holds the 161 * final result. You then call {@link ValueAndCloser#closeAsync()} to close the captured objects. 162 * 163 * <pre>{@code 164 * ClosingFuture.submit( 165 * closer -> closer.eventuallyClose(database.newTransaction(), closingExecutor), 166 * executor) 167 * .transformAsync((closer, transaction) -> transaction.queryClosingFuture("..."), executor) 168 * .transform((closer, result) -> result.get("userName"), directExecutor()) 169 * .catching(DBException.class, e -> "no user", directExecutor()) 170 * .finishToValueAndCloser( 171 * valueAndCloser -> this.userNameValueAndCloser = valueAndCloser, executor); 172 * 173 * // later 174 * try { // get() will throw if the operation failed or was cancelled. 175 * UserName userName = userNameValueAndCloser.get(); 176 * // do something with userName 177 * } finally { 178 * userNameValueAndCloser.closeAsync(); 179 * } 180 * }</pre> 181 * 182 * In this example, when {@code userNameValueAndCloser.closeAsync()} is called, the transaction and 183 * the query result cursor will both be closed, even if the operation is cancelled or fails. 184 * 185 * <p>Note that if you don't call {@code closeAsync()}, the captured objects will not be closed. The 186 * automatic-closing approach described above is safer. 187 * 188 * @param <V> the type of the value of this step 189 * @since 30.0 190 */ 191// TODO(dpb): Consider reusing one CloseableList for the entire pipeline, modulo combinations. 192@DoNotMock("Use ClosingFuture.from(Futures.immediate*Future)") 193@J2ktIncompatible 194@ElementTypesAreNonnullByDefault 195// TODO(dpb): GWT compatibility. 196public final class ClosingFuture<V extends @Nullable Object> { 197 198 private static final LazyLogger logger = new LazyLogger(ClosingFuture.class); 199 200 /** 201 * An object that can capture objects to be closed later, when a {@link ClosingFuture} pipeline is 202 * done. 203 */ 204 public static final class DeferredCloser { 205 @RetainedWith private final CloseableList list; 206 207 DeferredCloser(CloseableList list) { 208 this.list = list; 209 } 210 211 /** 212 * Captures an object to be closed when a {@link ClosingFuture} pipeline is done. 213 * 214 * <p>For users of the {@code -jre} flavor of Guava, the object can be any {@code 215 * AutoCloseable}. For users of the {@code -android} flavor, the object must be a {@code 216 * Closeable}. (For more about the flavors, see <a 217 * href="https://github.com/google/guava#adding-guava-to-your-build">Adding Guava to your 218 * build</a>.) 219 * 220 * <p>Be careful when targeting an older SDK than you are building against (most commonly when 221 * building for Android): Ensure that any object you pass implements the interface not just in 222 * your current SDK version but also at the oldest version you support. For example, <a 223 * href="https://developer.android.com/sdk/api_diff/16/">API Level 16</a> is the first version 224 * in which {@code Cursor} is {@code Closeable}. To support older versions, pass a wrapper 225 * {@code Closeable} with a method reference like {@code cursor::close}. 226 * 227 * <p>Note that this method is still binary-compatible between flavors because the erasure of 228 * its parameter type is {@code Object}, not {@code AutoCloseable} or {@code Closeable}. 229 * 230 * @param closeable the object to be closed (see notes above) 231 * @param closingExecutor the object will be closed on this executor 232 * @return the first argument 233 */ 234 @CanIgnoreReturnValue 235 @ParametricNullness 236 public <C extends @Nullable Object & @Nullable AutoCloseable> C eventuallyClose( 237 @ParametricNullness C closeable, Executor closingExecutor) { 238 checkNotNull(closingExecutor); 239 if (closeable != null) { 240 list.add(closeable, closingExecutor); 241 } 242 return closeable; 243 } 244 } 245 246 /** 247 * An operation that computes a result. 248 * 249 * @param <V> the type of the result 250 */ 251 @FunctionalInterface 252 public interface ClosingCallable<V extends @Nullable Object> { 253 /** 254 * Computes a result, or throws an exception if unable to do so. 255 * 256 * <p>Any objects that are passed to {@link DeferredCloser#eventuallyClose(Object, Executor) 257 * closer.eventuallyClose()} will be closed when the {@link ClosingFuture} pipeline is done (but 258 * not before this method completes), even if this method throws or the pipeline is cancelled. 259 */ 260 @ParametricNullness 261 V call(DeferredCloser closer) throws Exception; 262 } 263 264 /** 265 * An operation that computes a {@link ClosingFuture} of a result. 266 * 267 * @param <V> the type of the result 268 * @since 30.1 269 */ 270 @FunctionalInterface 271 public interface AsyncClosingCallable<V extends @Nullable Object> { 272 /** 273 * Computes a result, or throws an exception if unable to do so. 274 * 275 * <p>Any objects that are passed to {@link DeferredCloser#eventuallyClose(Object, Executor) 276 * closer.eventuallyClose()} will be closed when the {@link ClosingFuture} pipeline is done (but 277 * not before this method completes), even if this method throws or the pipeline is cancelled. 278 */ 279 ClosingFuture<V> call(DeferredCloser closer) throws Exception; 280 } 281 282 /** 283 * A function from an input to a result. 284 * 285 * @param <T> the type of the input to the function 286 * @param <U> the type of the result of the function 287 */ 288 @FunctionalInterface 289 public interface ClosingFunction<T extends @Nullable Object, U extends @Nullable Object> { 290 291 /** 292 * Applies this function to an input, or throws an exception if unable to do so. 293 * 294 * <p>Any objects that are passed to {@link DeferredCloser#eventuallyClose(Object, Executor) 295 * closer.eventuallyClose()} will be closed when the {@link ClosingFuture} pipeline is done (but 296 * not before this method completes), even if this method throws or the pipeline is cancelled. 297 */ 298 @ParametricNullness 299 U apply(DeferredCloser closer, @ParametricNullness T input) throws Exception; 300 } 301 302 /** 303 * A function from an input to a {@link ClosingFuture} of a result. 304 * 305 * @param <T> the type of the input to the function 306 * @param <U> the type of the result of the function 307 */ 308 @FunctionalInterface 309 public interface AsyncClosingFunction<T extends @Nullable Object, U extends @Nullable Object> { 310 /** 311 * Applies this function to an input, or throws an exception if unable to do so. 312 * 313 * <p>Any objects that are passed to {@link DeferredCloser#eventuallyClose(Object, Executor) 314 * closer.eventuallyClose()} will be closed when the {@link ClosingFuture} pipeline is done (but 315 * not before this method completes), even if this method throws or the pipeline is cancelled. 316 */ 317 ClosingFuture<U> apply(DeferredCloser closer, @ParametricNullness T input) throws Exception; 318 } 319 320 /** 321 * An object that holds the final result of an asynchronous {@link ClosingFuture} operation and 322 * allows the user to close all the closeable objects that were captured during it for later 323 * closing. 324 * 325 * <p>The asynchronous operation will have completed before this object is created. 326 * 327 * @param <V> the type of the value of a successful operation 328 * @see ClosingFuture#finishToValueAndCloser(ValueAndCloserConsumer, Executor) 329 */ 330 public static final class ValueAndCloser<V extends @Nullable Object> { 331 332 private final ClosingFuture<? extends V> closingFuture; 333 334 ValueAndCloser(ClosingFuture<? extends V> closingFuture) { 335 this.closingFuture = checkNotNull(closingFuture); 336 } 337 338 /** 339 * Returns the final value of the associated {@link ClosingFuture}, or throws an exception as 340 * {@link Future#get()} would. 341 * 342 * <p>Because the asynchronous operation has already completed, this method is synchronous and 343 * returns immediately. 344 * 345 * @throws CancellationException if the computation was cancelled 346 * @throws ExecutionException if the computation threw an exception 347 */ 348 @ParametricNullness 349 public V get() throws ExecutionException { 350 return getDone(closingFuture.future); 351 } 352 353 /** 354 * Starts closing all closeable objects captured during the {@link ClosingFuture}'s asynchronous 355 * operation on the {@link Executor}s specified by calls to {@link 356 * DeferredCloser#eventuallyClose(Object, Executor)}. 357 * 358 * <p>If any such calls specified {@link MoreExecutors#directExecutor()}, those objects will be 359 * closed synchronously. 360 * 361 * <p>Idempotent: objects will be closed at most once. 362 */ 363 public void closeAsync() { 364 closingFuture.close(); 365 } 366 } 367 368 /** 369 * Represents an operation that accepts a {@link ValueAndCloser} for the last step in a {@link 370 * ClosingFuture} pipeline. 371 * 372 * @param <V> the type of the final value of a successful pipeline 373 * @see ClosingFuture#finishToValueAndCloser(ValueAndCloserConsumer, Executor) 374 */ 375 @FunctionalInterface 376 public interface ValueAndCloserConsumer<V extends @Nullable Object> { 377 378 /** Accepts a {@link ValueAndCloser} for the last step in a {@link ClosingFuture} pipeline. */ 379 void accept(ValueAndCloser<V> valueAndCloser); 380 } 381 382 /** 383 * Starts a {@link ClosingFuture} pipeline by submitting a callable block to an executor. 384 * 385 * @throws java.util.concurrent.RejectedExecutionException if the task cannot be scheduled for 386 * execution 387 */ 388 public static <V extends @Nullable Object> ClosingFuture<V> submit( 389 ClosingCallable<V> callable, Executor executor) { 390 return new ClosingFuture<>(callable, executor); 391 } 392 393 /** 394 * Starts a {@link ClosingFuture} pipeline by submitting a callable block to an executor. 395 * 396 * @throws java.util.concurrent.RejectedExecutionException if the task cannot be scheduled for 397 * execution 398 * @since 30.1 399 */ 400 public static <V extends @Nullable Object> ClosingFuture<V> submitAsync( 401 AsyncClosingCallable<V> callable, Executor executor) { 402 return new ClosingFuture<>(callable, executor); 403 } 404 405 /** 406 * Starts a {@link ClosingFuture} pipeline with a {@link ListenableFuture}. 407 * 408 * <p>{@code future}'s value will not be closed when the pipeline is done even if {@code V} 409 * implements {@link Closeable}. In order to start a pipeline with a value that will be closed 410 * when the pipeline is done, use {@link #submit(ClosingCallable, Executor)} instead. 411 */ 412 public static <V extends @Nullable Object> ClosingFuture<V> from(ListenableFuture<V> future) { 413 return new ClosingFuture<V>(future); 414 } 415 416 /** 417 * Starts a {@link ClosingFuture} pipeline with a {@link ListenableFuture}. 418 * 419 * <p>If {@code future} succeeds, its value will be closed (using {@code closingExecutor)}) when 420 * the pipeline is done, even if the pipeline is canceled or fails. 421 * 422 * <p>Cancelling the pipeline will not cancel {@code future}, so that the pipeline can access its 423 * value in order to close it. 424 * 425 * @param future the future to create the {@code ClosingFuture} from. For discussion of the 426 * future's result type {@code C}, see {@link DeferredCloser#eventuallyClose(Object, 427 * Executor)}. 428 * @param closingExecutor the future's result will be closed on this executor 429 * @deprecated Creating {@link Future}s of closeable types is dangerous in general because the 430 * underlying value may never be closed if the {@link Future} is canceled after its operation 431 * begins. Consider replacing code that creates {@link ListenableFuture}s of closeable types, 432 * including those that pass them to this method, with {@link #submit(ClosingCallable, 433 * Executor)} in order to ensure that resources do not leak. Or, to start a pipeline with a 434 * {@link ListenableFuture} that doesn't create values that should be closed, use {@link 435 * ClosingFuture#from}. 436 */ 437 @Deprecated 438 public static <C extends @Nullable Object & @Nullable AutoCloseable> 439 ClosingFuture<C> eventuallyClosing( 440 ListenableFuture<C> future, final Executor closingExecutor) { 441 checkNotNull(closingExecutor); 442 final ClosingFuture<C> closingFuture = new ClosingFuture<>(nonCancellationPropagating(future)); 443 Futures.addCallback( 444 future, 445 new FutureCallback<@Nullable AutoCloseable>() { 446 @Override 447 public void onSuccess(@CheckForNull AutoCloseable result) { 448 closingFuture.closeables.closer.eventuallyClose(result, closingExecutor); 449 } 450 451 @Override 452 public void onFailure(Throwable t) {} 453 }, 454 directExecutor()); 455 return closingFuture; 456 } 457 458 /** 459 * Starts specifying how to combine {@link ClosingFuture}s into a single pipeline. 460 * 461 * @throws IllegalStateException if a {@code ClosingFuture} has already been derived from any of 462 * the {@code futures}, or if any has already been {@linkplain #finishToFuture() finished} 463 */ 464 public static Combiner whenAllComplete(Iterable<? extends ClosingFuture<?>> futures) { 465 return new Combiner(false, futures); 466 } 467 468 /** 469 * Starts specifying how to combine {@link ClosingFuture}s into a single pipeline. 470 * 471 * @throws IllegalStateException if a {@code ClosingFuture} has already been derived from any of 472 * the arguments, or if any has already been {@linkplain #finishToFuture() finished} 473 */ 474 public static Combiner whenAllComplete( 475 ClosingFuture<?> future1, ClosingFuture<?>... moreFutures) { 476 return whenAllComplete(asList(future1, moreFutures)); 477 } 478 479 /** 480 * Starts specifying how to combine {@link ClosingFuture}s into a single pipeline, assuming they 481 * all succeed. If any fail, the resulting pipeline will fail. 482 * 483 * @throws IllegalStateException if a {@code ClosingFuture} has already been derived from any of 484 * the {@code futures}, or if any has already been {@linkplain #finishToFuture() finished} 485 */ 486 public static Combiner whenAllSucceed(Iterable<? extends ClosingFuture<?>> futures) { 487 return new Combiner(true, futures); 488 } 489 490 /** 491 * Starts specifying how to combine two {@link ClosingFuture}s into a single pipeline, assuming 492 * they all succeed. If any fail, the resulting pipeline will fail. 493 * 494 * <p>Calling this method allows you to use lambdas or method references typed with the types of 495 * the input {@link ClosingFuture}s. 496 * 497 * @throws IllegalStateException if a {@code ClosingFuture} has already been derived from any of 498 * the arguments, or if any has already been {@linkplain #finishToFuture() finished} 499 */ 500 public static <V1 extends @Nullable Object, V2 extends @Nullable Object> 501 Combiner2<V1, V2> whenAllSucceed(ClosingFuture<V1> future1, ClosingFuture<V2> future2) { 502 return new Combiner2<>(future1, future2); 503 } 504 505 /** 506 * Starts specifying how to combine three {@link ClosingFuture}s into a single pipeline, assuming 507 * they all succeed. If any fail, the resulting pipeline will fail. 508 * 509 * <p>Calling this method allows you to use lambdas or method references typed with the types of 510 * the input {@link ClosingFuture}s. 511 * 512 * @throws IllegalStateException if a {@code ClosingFuture} has already been derived from any of 513 * the arguments, or if any has already been {@linkplain #finishToFuture() finished} 514 */ 515 public static < 516 V1 extends @Nullable Object, V2 extends @Nullable Object, V3 extends @Nullable Object> 517 Combiner3<V1, V2, V3> whenAllSucceed( 518 ClosingFuture<V1> future1, ClosingFuture<V2> future2, ClosingFuture<V3> future3) { 519 return new Combiner3<>(future1, future2, future3); 520 } 521 522 /** 523 * Starts specifying how to combine four {@link ClosingFuture}s into a single pipeline, assuming 524 * they all succeed. If any fail, the resulting pipeline will fail. 525 * 526 * <p>Calling this method allows you to use lambdas or method references typed with the types of 527 * the input {@link ClosingFuture}s. 528 * 529 * @throws IllegalStateException if a {@code ClosingFuture} has already been derived from any of 530 * the arguments, or if any has already been {@linkplain #finishToFuture() finished} 531 */ 532 public static < 533 V1 extends @Nullable Object, 534 V2 extends @Nullable Object, 535 V3 extends @Nullable Object, 536 V4 extends @Nullable Object> 537 Combiner4<V1, V2, V3, V4> whenAllSucceed( 538 ClosingFuture<V1> future1, 539 ClosingFuture<V2> future2, 540 ClosingFuture<V3> future3, 541 ClosingFuture<V4> future4) { 542 return new Combiner4<>(future1, future2, future3, future4); 543 } 544 545 /** 546 * Starts specifying how to combine five {@link ClosingFuture}s into a single pipeline, assuming 547 * they all succeed. If any fail, the resulting pipeline will fail. 548 * 549 * <p>Calling this method allows you to use lambdas or method references typed with the types of 550 * the input {@link ClosingFuture}s. 551 * 552 * @throws IllegalStateException if a {@code ClosingFuture} has already been derived from any of 553 * the arguments, or if any has already been {@linkplain #finishToFuture() finished} 554 */ 555 public static < 556 V1 extends @Nullable Object, 557 V2 extends @Nullable Object, 558 V3 extends @Nullable Object, 559 V4 extends @Nullable Object, 560 V5 extends @Nullable Object> 561 Combiner5<V1, V2, V3, V4, V5> whenAllSucceed( 562 ClosingFuture<V1> future1, 563 ClosingFuture<V2> future2, 564 ClosingFuture<V3> future3, 565 ClosingFuture<V4> future4, 566 ClosingFuture<V5> future5) { 567 return new Combiner5<>(future1, future2, future3, future4, future5); 568 } 569 570 /** 571 * Starts specifying how to combine {@link ClosingFuture}s into a single pipeline, assuming they 572 * all succeed. If any fail, the resulting pipeline will fail. 573 * 574 * @throws IllegalStateException if a {@code ClosingFuture} has already been derived from any of 575 * the arguments, or if any has already been {@linkplain #finishToFuture() finished} 576 */ 577 public static Combiner whenAllSucceed( 578 ClosingFuture<?> future1, 579 ClosingFuture<?> future2, 580 ClosingFuture<?> future3, 581 ClosingFuture<?> future4, 582 ClosingFuture<?> future5, 583 ClosingFuture<?> future6, 584 ClosingFuture<?>... moreFutures) { 585 return whenAllSucceed( 586 FluentIterable.of(future1, future2, future3, future4, future5, future6) 587 .append(moreFutures)); 588 } 589 590 private final AtomicReference<State> state = new AtomicReference<>(OPEN); 591 private final CloseableList closeables = new CloseableList(); 592 private final FluentFuture<V> future; 593 594 private ClosingFuture(ListenableFuture<V> future) { 595 this.future = FluentFuture.from(future); 596 } 597 598 private ClosingFuture(final ClosingCallable<V> callable, Executor executor) { 599 checkNotNull(callable); 600 TrustedListenableFutureTask<V> task = 601 TrustedListenableFutureTask.create( 602 new Callable<V>() { 603 @Override 604 @ParametricNullness 605 public V call() throws Exception { 606 return callable.call(closeables.closer); 607 } 608 609 @Override 610 public String toString() { 611 return callable.toString(); 612 } 613 }); 614 executor.execute(task); 615 this.future = task; 616 } 617 618 private ClosingFuture(final AsyncClosingCallable<V> callable, Executor executor) { 619 checkNotNull(callable); 620 TrustedListenableFutureTask<V> task = 621 TrustedListenableFutureTask.create( 622 new AsyncCallable<V>() { 623 @Override 624 public ListenableFuture<V> call() throws Exception { 625 CloseableList newCloseables = new CloseableList(); 626 try { 627 ClosingFuture<V> closingFuture = callable.call(newCloseables.closer); 628 closingFuture.becomeSubsumedInto(closeables); 629 return closingFuture.future; 630 } finally { 631 closeables.add(newCloseables, directExecutor()); 632 } 633 } 634 635 @Override 636 public String toString() { 637 return callable.toString(); 638 } 639 }); 640 executor.execute(task); 641 this.future = task; 642 } 643 644 /** 645 * Returns a future that finishes when this step does. Calling {@code get()} on the returned 646 * future returns {@code null} if the step is successful or throws the same exception that would 647 * be thrown by calling {@code finishToFuture().get()} if this were the last step. Calling {@code 648 * cancel()} on the returned future has no effect on the {@code ClosingFuture} pipeline. 649 * 650 * <p>{@code statusFuture} differs from most methods on {@code ClosingFuture}: You can make calls 651 * to {@code statusFuture} <i>in addition to</i> the call you make to {@link #finishToFuture()} or 652 * a derivation method <i>on the same instance</i>. This is important because calling {@code 653 * statusFuture} alone does not provide a way to close the pipeline. 654 */ 655 public ListenableFuture<?> statusFuture() { 656 return nonCancellationPropagating(future.transform(constant(null), directExecutor())); 657 } 658 659 /** 660 * Returns a new {@code ClosingFuture} pipeline step derived from this one by applying a function 661 * to its value. The function can use a {@link DeferredCloser} to capture objects to be closed 662 * when the pipeline is done. 663 * 664 * <p>If this {@code ClosingFuture} fails, the function will not be called, and the derived {@code 665 * ClosingFuture} will be equivalent to this one. 666 * 667 * <p>If the function throws an exception, that exception is used as the result of the derived 668 * {@code ClosingFuture}. 669 * 670 * <p>Example usage: 671 * 672 * <pre>{@code 673 * ClosingFuture<List<Row>> rowsFuture = 674 * queryFuture.transform((closer, result) -> result.getRows(), executor); 675 * }</pre> 676 * 677 * <p>When selecting an executor, note that {@code directExecutor} is dangerous in some cases. See 678 * the discussion in the {@link ListenableFuture#addListener} documentation. All its warnings 679 * about heavyweight listeners are also applicable to heavyweight functions passed to this method. 680 * 681 * <p>After calling this method, you may not call {@link #finishToFuture()}, {@link 682 * #finishToValueAndCloser(ValueAndCloserConsumer, Executor)}, or any other derivation method on 683 * the original {@code ClosingFuture} instance. 684 * 685 * @param function transforms the value of this step to the value of the derived step 686 * @param executor executor to run the function in 687 * @return the derived step 688 * @throws IllegalStateException if a {@code ClosingFuture} has already been derived from this 689 * one, or if this {@code ClosingFuture} has already been {@linkplain #finishToFuture() 690 * finished} 691 */ 692 public <U extends @Nullable Object> ClosingFuture<U> transform( 693 final ClosingFunction<? super V, U> function, Executor executor) { 694 checkNotNull(function); 695 AsyncFunction<V, U> applyFunction = 696 new AsyncFunction<V, U>() { 697 @Override 698 public ListenableFuture<U> apply(V input) throws Exception { 699 return closeables.applyClosingFunction(function, input); 700 } 701 702 @Override 703 public String toString() { 704 return function.toString(); 705 } 706 }; 707 // TODO(dpb): Switch to future.transformSync when that exists (passing a throwing function). 708 return derive(future.transformAsync(applyFunction, executor)); 709 } 710 711 /** 712 * Returns a new {@code ClosingFuture} pipeline step derived from this one by applying a function 713 * that returns a {@code ClosingFuture} to its value. The function can use a {@link 714 * DeferredCloser} to capture objects to be closed when the pipeline is done (other than those 715 * captured by the returned {@link ClosingFuture}). 716 * 717 * <p>If this {@code ClosingFuture} succeeds, the derived one will be equivalent to the one 718 * returned by the function. 719 * 720 * <p>If this {@code ClosingFuture} fails, the function will not be called, and the derived {@code 721 * ClosingFuture} will be equivalent to this one. 722 * 723 * <p>If the function throws an exception, that exception is used as the result of the derived 724 * {@code ClosingFuture}. But if the exception is thrown after the function creates a {@code 725 * ClosingFuture}, then none of the closeable objects in that {@code ClosingFuture} will be 726 * closed. 727 * 728 * <p>Usage guidelines for this method: 729 * 730 * <ul> 731 * <li>Use this method only when calling an API that returns a {@link ListenableFuture} or a 732 * {@code ClosingFuture}. If possible, prefer calling {@link #transform(ClosingFunction, 733 * Executor)} instead, with a function that returns the next value directly. 734 * <li>Call {@link DeferredCloser#eventuallyClose(Object, Executor) closer.eventuallyClose()} 735 * for every closeable object this step creates in order to capture it for later closing. 736 * <li>Return a {@code ClosingFuture}. To turn a {@link ListenableFuture} into a {@code 737 * ClosingFuture} call {@link #from(ListenableFuture)}. 738 * <li>In case this step doesn't create new closeables, you can adapt an API that returns a 739 * {@link ListenableFuture} to return a {@code ClosingFuture} by wrapping it with a call to 740 * {@link #withoutCloser(AsyncFunction)} 741 * </ul> 742 * 743 * <p>Example usage: 744 * 745 * <pre>{@code 746 * // Result.getRowsClosingFuture() returns a ClosingFuture. 747 * ClosingFuture<List<Row>> rowsFuture = 748 * queryFuture.transformAsync((closer, result) -> result.getRowsClosingFuture(), executor); 749 * 750 * // Result.writeRowsToOutputStreamFuture() returns a ListenableFuture that resolves to the 751 * // number of written rows. openOutputFile() returns a FileOutputStream (which implements 752 * // Closeable). 753 * ClosingFuture<Integer> rowsFuture2 = 754 * queryFuture.transformAsync( 755 * (closer, result) -> { 756 * FileOutputStream fos = closer.eventuallyClose(openOutputFile(), closingExecutor); 757 * return ClosingFuture.from(result.writeRowsToOutputStreamFuture(fos)); 758 * }, 759 * executor); 760 * 761 * // Result.getRowsFuture() returns a ListenableFuture (no new closeables are created). 762 * ClosingFuture<List<Row>> rowsFuture3 = 763 * queryFuture.transformAsync(withoutCloser(Result::getRowsFuture), executor); 764 * 765 * }</pre> 766 * 767 * <p>When selecting an executor, note that {@code directExecutor} is dangerous in some cases. See 768 * the discussion in the {@link ListenableFuture#addListener} documentation. All its warnings 769 * about heavyweight listeners are also applicable to heavyweight functions passed to this method. 770 * (Specifically, {@code directExecutor} functions should avoid heavyweight operations inside 771 * {@code AsyncClosingFunction.apply}. Any heavyweight operations should occur in other threads 772 * responsible for completing the returned {@code ClosingFuture}.) 773 * 774 * <p>After calling this method, you may not call {@link #finishToFuture()}, {@link 775 * #finishToValueAndCloser(ValueAndCloserConsumer, Executor)}, or any other derivation method on 776 * the original {@code ClosingFuture} instance. 777 * 778 * @param function transforms the value of this step to a {@code ClosingFuture} with the value of 779 * the derived step 780 * @param executor executor to run the function in 781 * @return the derived step 782 * @throws IllegalStateException if a {@code ClosingFuture} has already been derived from this 783 * one, or if this {@code ClosingFuture} has already been {@linkplain #finishToFuture() 784 * finished} 785 */ 786 public <U extends @Nullable Object> ClosingFuture<U> transformAsync( 787 final AsyncClosingFunction<? super V, U> function, Executor executor) { 788 checkNotNull(function); 789 AsyncFunction<V, U> applyFunction = 790 new AsyncFunction<V, U>() { 791 @Override 792 public ListenableFuture<U> apply(V input) throws Exception { 793 return closeables.applyAsyncClosingFunction(function, input); 794 } 795 796 @Override 797 public String toString() { 798 return function.toString(); 799 } 800 }; 801 return derive(future.transformAsync(applyFunction, executor)); 802 } 803 804 /** 805 * Returns an {@link AsyncClosingFunction} that applies an {@link AsyncFunction} to an input, 806 * ignoring the DeferredCloser and returning a {@code ClosingFuture} derived from the returned 807 * {@link ListenableFuture}. 808 * 809 * <p>Use this method to pass a transformation to {@link #transformAsync(AsyncClosingFunction, 810 * Executor)} or to {@link #catchingAsync(Class, AsyncClosingFunction, Executor)} as long as it 811 * meets these conditions: 812 * 813 * <ul> 814 * <li>It does not need to capture any {@link Closeable} objects by calling {@link 815 * DeferredCloser#eventuallyClose(Object, Executor)}. 816 * <li>It returns a {@link ListenableFuture}. 817 * </ul> 818 * 819 * <p>Example usage: 820 * 821 * <pre>{@code 822 * // Result.getRowsFuture() returns a ListenableFuture. 823 * ClosingFuture<List<Row>> rowsFuture = 824 * queryFuture.transformAsync(withoutCloser(Result::getRowsFuture), executor); 825 * }</pre> 826 * 827 * @param function transforms the value of a {@code ClosingFuture} step to a {@link 828 * ListenableFuture} with the value of a derived step 829 */ 830 public static <V extends @Nullable Object, U extends @Nullable Object> 831 AsyncClosingFunction<V, U> withoutCloser(final AsyncFunction<V, U> function) { 832 checkNotNull(function); 833 return new AsyncClosingFunction<V, U>() { 834 @Override 835 public ClosingFuture<U> apply(DeferredCloser closer, V input) throws Exception { 836 return ClosingFuture.from(function.apply(input)); 837 } 838 }; 839 } 840 841 /** 842 * Returns a new {@code ClosingFuture} pipeline step derived from this one by applying a function 843 * to its exception if it is an instance of a given exception type. The function can use a {@link 844 * DeferredCloser} to capture objects to be closed when the pipeline is done. 845 * 846 * <p>If this {@code ClosingFuture} succeeds or fails with a different exception type, the 847 * function will not be called, and the derived {@code ClosingFuture} will be equivalent to this 848 * one. 849 * 850 * <p>If the function throws an exception, that exception is used as the result of the derived 851 * {@code ClosingFuture}. 852 * 853 * <p>Example usage: 854 * 855 * <pre>{@code 856 * ClosingFuture<QueryResult> queryFuture = 857 * queryFuture.catching( 858 * QueryException.class, (closer, x) -> Query.emptyQueryResult(), executor); 859 * }</pre> 860 * 861 * <p>When selecting an executor, note that {@code directExecutor} is dangerous in some cases. See 862 * the discussion in the {@link ListenableFuture#addListener} documentation. All its warnings 863 * about heavyweight listeners are also applicable to heavyweight functions passed to this method. 864 * 865 * <p>After calling this method, you may not call {@link #finishToFuture()}, {@link 866 * #finishToValueAndCloser(ValueAndCloserConsumer, Executor)}, or any other derivation method on 867 * the original {@code ClosingFuture} instance. 868 * 869 * @param exceptionType the exception type that triggers use of {@code fallback}. The exception 870 * type is matched against this step's exception. "This step's exception" means the cause of 871 * the {@link ExecutionException} thrown by {@link Future#get()} on the {@link Future} 872 * underlying this step or, if {@code get()} throws a different kind of exception, that 873 * exception itself. To avoid hiding bugs and other unrecoverable errors, callers should 874 * prefer more specific types, avoiding {@code Throwable.class} in particular. 875 * @param fallback the function to be called if this step fails with the expected exception type. 876 * The function's argument is this step's exception. "This step's exception" means the cause 877 * of the {@link ExecutionException} thrown by {@link Future#get()} on the {@link Future} 878 * underlying this step or, if {@code get()} throws a different kind of exception, that 879 * exception itself. 880 * @param executor the executor that runs {@code fallback} if the input fails 881 */ 882 public <X extends Throwable> ClosingFuture<V> catching( 883 Class<X> exceptionType, ClosingFunction<? super X, ? extends V> fallback, Executor executor) { 884 return catchingMoreGeneric(exceptionType, fallback, executor); 885 } 886 887 // Avoids generic type capture inconsistency problems where |? extends V| is incompatible with V. 888 private <X extends Throwable, W extends V> ClosingFuture<V> catchingMoreGeneric( 889 Class<X> exceptionType, final ClosingFunction<? super X, W> fallback, Executor executor) { 890 checkNotNull(fallback); 891 AsyncFunction<X, W> applyFallback = 892 new AsyncFunction<X, W>() { 893 @Override 894 public ListenableFuture<W> apply(X exception) throws Exception { 895 return closeables.applyClosingFunction(fallback, exception); 896 } 897 898 @Override 899 public String toString() { 900 return fallback.toString(); 901 } 902 }; 903 // TODO(dpb): Switch to future.catchingSync when that exists (passing a throwing function). 904 return derive(future.catchingAsync(exceptionType, applyFallback, executor)); 905 } 906 907 /** 908 * Returns a new {@code ClosingFuture} pipeline step derived from this one by applying a function 909 * that returns a {@code ClosingFuture} to its exception if it is an instance of a given exception 910 * type. The function can use a {@link DeferredCloser} to capture objects to be closed when the 911 * pipeline is done (other than those captured by the returned {@link ClosingFuture}). 912 * 913 * <p>If this {@code ClosingFuture} fails with an exception of the given type, the derived {@code 914 * ClosingFuture} will be equivalent to the one returned by the function. 915 * 916 * <p>If this {@code ClosingFuture} succeeds or fails with a different exception type, the 917 * function will not be called, and the derived {@code ClosingFuture} will be equivalent to this 918 * one. 919 * 920 * <p>If the function throws an exception, that exception is used as the result of the derived 921 * {@code ClosingFuture}. But if the exception is thrown after the function creates a {@code 922 * ClosingFuture}, then none of the closeable objects in that {@code ClosingFuture} will be 923 * closed. 924 * 925 * <p>Usage guidelines for this method: 926 * 927 * <ul> 928 * <li>Use this method only when calling an API that returns a {@link ListenableFuture} or a 929 * {@code ClosingFuture}. If possible, prefer calling {@link #catching(Class, 930 * ClosingFunction, Executor)} instead, with a function that returns the next value 931 * directly. 932 * <li>Call {@link DeferredCloser#eventuallyClose(Object, Executor) closer.eventuallyClose()} 933 * for every closeable object this step creates in order to capture it for later closing. 934 * <li>Return a {@code ClosingFuture}. To turn a {@link ListenableFuture} into a {@code 935 * ClosingFuture} call {@link #from(ListenableFuture)}. 936 * <li>In case this step doesn't create new closeables, you can adapt an API that returns a 937 * {@link ListenableFuture} to return a {@code ClosingFuture} by wrapping it with a call to 938 * {@link #withoutCloser(AsyncFunction)} 939 * </ul> 940 * 941 * <p>Example usage: 942 * 943 * <pre>{@code 944 * // Fall back to a secondary input stream in case of IOException. 945 * ClosingFuture<InputStream> inputFuture = 946 * firstInputFuture.catchingAsync( 947 * IOException.class, (closer, x) -> secondaryInputStreamClosingFuture(), executor); 948 * } 949 * }</pre> 950 * 951 * <p>When selecting an executor, note that {@code directExecutor} is dangerous in some cases. See 952 * the discussion in the {@link ListenableFuture#addListener} documentation. All its warnings 953 * about heavyweight listeners are also applicable to heavyweight functions passed to this method. 954 * (Specifically, {@code directExecutor} functions should avoid heavyweight operations inside 955 * {@code AsyncClosingFunction.apply}. Any heavyweight operations should occur in other threads 956 * responsible for completing the returned {@code ClosingFuture}.) 957 * 958 * <p>After calling this method, you may not call {@link #finishToFuture()}, {@link 959 * #finishToValueAndCloser(ValueAndCloserConsumer, Executor)}, or any other derivation method on 960 * the original {@code ClosingFuture} instance. 961 * 962 * @param exceptionType the exception type that triggers use of {@code fallback}. The exception 963 * type is matched against this step's exception. "This step's exception" means the cause of 964 * the {@link ExecutionException} thrown by {@link Future#get()} on the {@link Future} 965 * underlying this step or, if {@code get()} throws a different kind of exception, that 966 * exception itself. To avoid hiding bugs and other unrecoverable errors, callers should 967 * prefer more specific types, avoiding {@code Throwable.class} in particular. 968 * @param fallback the function to be called if this step fails with the expected exception type. 969 * The function's argument is this step's exception. "This step's exception" means the cause 970 * of the {@link ExecutionException} thrown by {@link Future#get()} on the {@link Future} 971 * underlying this step or, if {@code get()} throws a different kind of exception, that 972 * exception itself. 973 * @param executor the executor that runs {@code fallback} if the input fails 974 */ 975 // TODO(dpb): Should this do something special if the function throws CancellationException or 976 // ExecutionException? 977 public <X extends Throwable> ClosingFuture<V> catchingAsync( 978 Class<X> exceptionType, 979 AsyncClosingFunction<? super X, ? extends V> fallback, 980 Executor executor) { 981 return catchingAsyncMoreGeneric(exceptionType, fallback, executor); 982 } 983 984 // Avoids generic type capture inconsistency problems where |? extends V| is incompatible with V. 985 private <X extends Throwable, W extends V> ClosingFuture<V> catchingAsyncMoreGeneric( 986 Class<X> exceptionType, 987 final AsyncClosingFunction<? super X, W> fallback, 988 Executor executor) { 989 checkNotNull(fallback); 990 AsyncFunction<X, W> asyncFunction = 991 new AsyncFunction<X, W>() { 992 @Override 993 public ListenableFuture<W> apply(X exception) throws Exception { 994 return closeables.applyAsyncClosingFunction(fallback, exception); 995 } 996 997 @Override 998 public String toString() { 999 return fallback.toString(); 1000 } 1001 }; 1002 return derive(future.catchingAsync(exceptionType, asyncFunction, executor)); 1003 } 1004 1005 /** 1006 * Marks this step as the last step in the {@code ClosingFuture} pipeline. 1007 * 1008 * <p>The returned {@link Future} is completed when the pipeline's computation completes, or when 1009 * the pipeline is cancelled. 1010 * 1011 * <p>All objects the pipeline has captured for closing will begin to be closed asynchronously 1012 * <b>after</b> the returned {@code Future} is done: the future completes before closing starts, 1013 * rather than once it has finished. 1014 * 1015 * <p>After calling this method, you may not call {@link 1016 * #finishToValueAndCloser(ValueAndCloserConsumer, Executor)}, this method, or any other 1017 * derivation method on the original {@code ClosingFuture} instance. 1018 * 1019 * @return a {@link Future} that represents the final value or exception of the pipeline 1020 */ 1021 public FluentFuture<V> finishToFuture() { 1022 if (compareAndUpdateState(OPEN, WILL_CLOSE)) { 1023 logger.get().log(FINER, "will close {0}", this); 1024 future.addListener( 1025 new Runnable() { 1026 @Override 1027 public void run() { 1028 checkAndUpdateState(WILL_CLOSE, CLOSING); 1029 close(); 1030 checkAndUpdateState(CLOSING, CLOSED); 1031 } 1032 }, 1033 directExecutor()); 1034 } else { 1035 switch (state.get()) { 1036 case SUBSUMED: 1037 throw new IllegalStateException( 1038 "Cannot call finishToFuture() after deriving another step"); 1039 1040 case WILL_CREATE_VALUE_AND_CLOSER: 1041 throw new IllegalStateException( 1042 "Cannot call finishToFuture() after calling finishToValueAndCloser()"); 1043 1044 case WILL_CLOSE: 1045 case CLOSING: 1046 case CLOSED: 1047 throw new IllegalStateException("Cannot call finishToFuture() twice"); 1048 1049 case OPEN: 1050 throw new AssertionError(); 1051 } 1052 } 1053 return future; 1054 } 1055 1056 /** 1057 * Marks this step as the last step in the {@code ClosingFuture} pipeline. When this step is done, 1058 * {@code receiver} will be called with an object that contains the result of the operation. The 1059 * receiver can store the {@link ValueAndCloser} outside the receiver for later synchronous use. 1060 * 1061 * <p>After calling this method, you may not call {@link #finishToFuture()}, this method again, or 1062 * any other derivation method on the original {@code ClosingFuture} instance. 1063 * 1064 * @param consumer a callback whose method will be called (using {@code executor}) when this 1065 * operation is done 1066 */ 1067 public void finishToValueAndCloser( 1068 final ValueAndCloserConsumer<? super V> consumer, Executor executor) { 1069 checkNotNull(consumer); 1070 if (!compareAndUpdateState(OPEN, WILL_CREATE_VALUE_AND_CLOSER)) { 1071 switch (state.get()) { 1072 case SUBSUMED: 1073 throw new IllegalStateException( 1074 "Cannot call finishToValueAndCloser() after deriving another step"); 1075 1076 case WILL_CLOSE: 1077 case CLOSING: 1078 case CLOSED: 1079 throw new IllegalStateException( 1080 "Cannot call finishToValueAndCloser() after calling finishToFuture()"); 1081 1082 case WILL_CREATE_VALUE_AND_CLOSER: 1083 throw new IllegalStateException("Cannot call finishToValueAndCloser() twice"); 1084 1085 case OPEN: 1086 break; 1087 } 1088 throw new AssertionError(state); 1089 } 1090 future.addListener( 1091 new Runnable() { 1092 @Override 1093 public void run() { 1094 provideValueAndCloser(consumer, ClosingFuture.this); 1095 } 1096 }, 1097 executor); 1098 } 1099 1100 private static <C extends @Nullable Object, V extends C> void provideValueAndCloser( 1101 ValueAndCloserConsumer<C> consumer, ClosingFuture<V> closingFuture) { 1102 consumer.accept(new ValueAndCloser<C>(closingFuture)); 1103 } 1104 1105 /** 1106 * Attempts to cancel execution of this step. This attempt will fail if the step has already 1107 * completed, has already been cancelled, or could not be cancelled for some other reason. If 1108 * successful, and this step has not started when {@code cancel} is called, this step should never 1109 * run. 1110 * 1111 * <p>If successful, causes the objects captured by this step (if already started) and its input 1112 * step(s) for later closing to be closed on their respective {@link Executor}s. If any such calls 1113 * specified {@link MoreExecutors#directExecutor()}, those objects will be closed synchronously. 1114 * 1115 * @param mayInterruptIfRunning {@code true} if the thread executing this task should be 1116 * interrupted; otherwise, in-progress tasks are allowed to complete, but the step will be 1117 * cancelled regardless 1118 * @return {@code false} if the step could not be cancelled, typically because it has already 1119 * completed normally; {@code true} otherwise 1120 */ 1121 @CanIgnoreReturnValue 1122 public boolean cancel(boolean mayInterruptIfRunning) { 1123 logger.get().log(FINER, "cancelling {0}", this); 1124 boolean cancelled = future.cancel(mayInterruptIfRunning); 1125 if (cancelled) { 1126 close(); 1127 } 1128 return cancelled; 1129 } 1130 1131 private void close() { 1132 logger.get().log(FINER, "closing {0}", this); 1133 closeables.close(); 1134 } 1135 1136 private <U extends @Nullable Object> ClosingFuture<U> derive(FluentFuture<U> future) { 1137 ClosingFuture<U> derived = new ClosingFuture<>(future); 1138 becomeSubsumedInto(derived.closeables); 1139 return derived; 1140 } 1141 1142 private void becomeSubsumedInto(CloseableList otherCloseables) { 1143 checkAndUpdateState(OPEN, SUBSUMED); 1144 otherCloseables.add(closeables, directExecutor()); 1145 } 1146 1147 /** 1148 * An object that can return the value of the {@link ClosingFuture}s that are passed to {@link 1149 * #whenAllComplete(Iterable)} or {@link #whenAllSucceed(Iterable)}. 1150 * 1151 * <p>Only for use by a {@link CombiningCallable} or {@link AsyncCombiningCallable} object. 1152 */ 1153 public static final class Peeker { 1154 private final ImmutableList<ClosingFuture<?>> futures; 1155 private volatile boolean beingCalled; 1156 1157 private Peeker(ImmutableList<ClosingFuture<?>> futures) { 1158 this.futures = checkNotNull(futures); 1159 } 1160 1161 /** 1162 * Returns the value of {@code closingFuture}. 1163 * 1164 * @throws ExecutionException if {@code closingFuture} is a failed step 1165 * @throws CancellationException if the {@code closingFuture}'s future was cancelled 1166 * @throws IllegalArgumentException if {@code closingFuture} is not one of the futures passed to 1167 * {@link #whenAllComplete(Iterable)} or {@link #whenAllComplete(Iterable)} 1168 * @throws IllegalStateException if called outside of a call to {@link 1169 * CombiningCallable#call(DeferredCloser, Peeker)} or {@link 1170 * AsyncCombiningCallable#call(DeferredCloser, Peeker)} 1171 */ 1172 @ParametricNullness 1173 public final <D extends @Nullable Object> D getDone(ClosingFuture<D> closingFuture) 1174 throws ExecutionException { 1175 checkState(beingCalled); 1176 checkArgument(futures.contains(closingFuture)); 1177 return Futures.getDone(closingFuture.future); 1178 } 1179 1180 @ParametricNullness 1181 private <V extends @Nullable Object> V call( 1182 CombiningCallable<V> combiner, CloseableList closeables) throws Exception { 1183 beingCalled = true; 1184 CloseableList newCloseables = new CloseableList(); 1185 try { 1186 return combiner.call(newCloseables.closer, this); 1187 } finally { 1188 closeables.add(newCloseables, directExecutor()); 1189 beingCalled = false; 1190 } 1191 } 1192 1193 private <V extends @Nullable Object> FluentFuture<V> callAsync( 1194 AsyncCombiningCallable<V> combiner, CloseableList closeables) throws Exception { 1195 beingCalled = true; 1196 CloseableList newCloseables = new CloseableList(); 1197 try { 1198 ClosingFuture<V> closingFuture = combiner.call(newCloseables.closer, this); 1199 closingFuture.becomeSubsumedInto(closeables); 1200 return closingFuture.future; 1201 } finally { 1202 closeables.add(newCloseables, directExecutor()); 1203 beingCalled = false; 1204 } 1205 } 1206 } 1207 1208 /** 1209 * A builder of a {@link ClosingFuture} step that is derived from more than one input step. 1210 * 1211 * <p>See {@link #whenAllComplete(Iterable)} and {@link #whenAllSucceed(Iterable)} for how to 1212 * instantiate this class. 1213 * 1214 * <p>Example: 1215 * 1216 * <pre>{@code 1217 * final ClosingFuture<BufferedReader> file1ReaderFuture = ...; 1218 * final ClosingFuture<BufferedReader> file2ReaderFuture = ...; 1219 * ListenableFuture<Integer> numberOfDifferentLines = 1220 * ClosingFuture.whenAllSucceed(file1ReaderFuture, file2ReaderFuture) 1221 * .call( 1222 * (closer, peeker) -> { 1223 * BufferedReader file1Reader = peeker.getDone(file1ReaderFuture); 1224 * BufferedReader file2Reader = peeker.getDone(file2ReaderFuture); 1225 * return countDifferentLines(file1Reader, file2Reader); 1226 * }, 1227 * executor) 1228 * .closing(executor); 1229 * }</pre> 1230 */ 1231 // TODO(cpovirk): Use simple name instead of fully qualified after we stop building with JDK 8. 1232 @com.google.errorprone.annotations.DoNotMock( 1233 "Use ClosingFuture.whenAllSucceed() or .whenAllComplete() instead.") 1234 public static class Combiner { 1235 1236 private final CloseableList closeables = new CloseableList(); 1237 1238 /** 1239 * An operation that returns a result and may throw an exception. 1240 * 1241 * @param <V> the type of the result 1242 */ 1243 @FunctionalInterface 1244 public interface CombiningCallable<V extends @Nullable Object> { 1245 /** 1246 * Computes a result, or throws an exception if unable to do so. 1247 * 1248 * <p>Any objects that are passed to {@link DeferredCloser#eventuallyClose(Object, Executor) 1249 * closer.eventuallyClose()} will be closed when the {@link ClosingFuture} pipeline is done 1250 * (but not before this method completes), even if this method throws or the pipeline is 1251 * cancelled. 1252 * 1253 * @param peeker used to get the value of any of the input futures 1254 */ 1255 @ParametricNullness 1256 V call(DeferredCloser closer, Peeker peeker) throws Exception; 1257 } 1258 1259 /** 1260 * An operation that returns a {@link ClosingFuture} result and may throw an exception. 1261 * 1262 * @param <V> the type of the result 1263 */ 1264 @FunctionalInterface 1265 public interface AsyncCombiningCallable<V extends @Nullable Object> { 1266 /** 1267 * Computes a {@link ClosingFuture} result, or throws an exception if unable to do so. 1268 * 1269 * <p>Any objects that are passed to {@link DeferredCloser#eventuallyClose(Object, Executor) 1270 * closer.eventuallyClose()} will be closed when the {@link ClosingFuture} pipeline is done 1271 * (but not before this method completes), even if this method throws or the pipeline is 1272 * cancelled. 1273 * 1274 * @param peeker used to get the value of any of the input futures 1275 */ 1276 ClosingFuture<V> call(DeferredCloser closer, Peeker peeker) throws Exception; 1277 } 1278 1279 private final boolean allMustSucceed; 1280 protected final ImmutableList<ClosingFuture<?>> inputs; 1281 1282 private Combiner(boolean allMustSucceed, Iterable<? extends ClosingFuture<?>> inputs) { 1283 this.allMustSucceed = allMustSucceed; 1284 this.inputs = ImmutableList.copyOf(inputs); 1285 for (ClosingFuture<?> input : inputs) { 1286 input.becomeSubsumedInto(closeables); 1287 } 1288 } 1289 1290 /** 1291 * Returns a new {@code ClosingFuture} pipeline step derived from the inputs by applying a 1292 * combining function to their values. The function can use a {@link DeferredCloser} to capture 1293 * objects to be closed when the pipeline is done. 1294 * 1295 * <p>If this combiner was returned by a {@link #whenAllSucceed} method and any of the inputs 1296 * fail, so will the returned step. 1297 * 1298 * <p>If the combiningCallable throws a {@code CancellationException}, the pipeline will be 1299 * cancelled. 1300 * 1301 * <p>If the combiningCallable throws an {@code ExecutionException}, the cause of the thrown 1302 * {@code ExecutionException} will be extracted and used as the failure of the derived step. 1303 */ 1304 public <V extends @Nullable Object> ClosingFuture<V> call( 1305 final CombiningCallable<V> combiningCallable, Executor executor) { 1306 Callable<V> callable = 1307 new Callable<V>() { 1308 @Override 1309 @ParametricNullness 1310 public V call() throws Exception { 1311 return new Peeker(inputs).call(combiningCallable, closeables); 1312 } 1313 1314 @Override 1315 public String toString() { 1316 return combiningCallable.toString(); 1317 } 1318 }; 1319 ClosingFuture<V> derived = new ClosingFuture<>(futureCombiner().call(callable, executor)); 1320 derived.closeables.add(closeables, directExecutor()); 1321 return derived; 1322 } 1323 1324 /** 1325 * Returns a new {@code ClosingFuture} pipeline step derived from the inputs by applying a 1326 * {@code ClosingFuture}-returning function to their values. The function can use a {@link 1327 * DeferredCloser} to capture objects to be closed when the pipeline is done (other than those 1328 * captured by the returned {@link ClosingFuture}). 1329 * 1330 * <p>If this combiner was returned by a {@link #whenAllSucceed} method and any of the inputs 1331 * fail, so will the returned step. 1332 * 1333 * <p>If the combiningCallable throws a {@code CancellationException}, the pipeline will be 1334 * cancelled. 1335 * 1336 * <p>If the combiningCallable throws an {@code ExecutionException}, the cause of the thrown 1337 * {@code ExecutionException} will be extracted and used as the failure of the derived step. 1338 * 1339 * <p>If the combiningCallable throws any other exception, it will be used as the failure of the 1340 * derived step. 1341 * 1342 * <p>If an exception is thrown after the combiningCallable creates a {@code ClosingFuture}, 1343 * then none of the closeable objects in that {@code ClosingFuture} will be closed. 1344 * 1345 * <p>Usage guidelines for this method: 1346 * 1347 * <ul> 1348 * <li>Use this method only when calling an API that returns a {@link ListenableFuture} or a 1349 * {@code ClosingFuture}. If possible, prefer calling {@link #call(CombiningCallable, 1350 * Executor)} instead, with a function that returns the next value directly. 1351 * <li>Call {@link DeferredCloser#eventuallyClose(Object, Executor) closer.eventuallyClose()} 1352 * for every closeable object this step creates in order to capture it for later closing. 1353 * <li>Return a {@code ClosingFuture}. To turn a {@link ListenableFuture} into a {@code 1354 * ClosingFuture} call {@link #from(ListenableFuture)}. 1355 * </ul> 1356 * 1357 * <p>The same warnings about doing heavyweight operations within {@link 1358 * ClosingFuture#transformAsync(AsyncClosingFunction, Executor)} apply here. 1359 */ 1360 public <V extends @Nullable Object> ClosingFuture<V> callAsync( 1361 final AsyncCombiningCallable<V> combiningCallable, Executor executor) { 1362 AsyncCallable<V> asyncCallable = 1363 new AsyncCallable<V>() { 1364 @Override 1365 public ListenableFuture<V> call() throws Exception { 1366 return new Peeker(inputs).callAsync(combiningCallable, closeables); 1367 } 1368 1369 @Override 1370 public String toString() { 1371 return combiningCallable.toString(); 1372 } 1373 }; 1374 ClosingFuture<V> derived = 1375 new ClosingFuture<>(futureCombiner().callAsync(asyncCallable, executor)); 1376 derived.closeables.add(closeables, directExecutor()); 1377 return derived; 1378 } 1379 1380 private FutureCombiner<@Nullable Object> futureCombiner() { 1381 return allMustSucceed 1382 ? Futures.whenAllSucceed(inputFutures()) 1383 : Futures.whenAllComplete(inputFutures()); 1384 } 1385 1386 1387 private ImmutableList<FluentFuture<?>> inputFutures() { 1388 return FluentIterable.from(inputs) 1389 .<FluentFuture<?>>transform(future -> future.future) 1390 .toList(); 1391 } 1392 } 1393 1394 /** 1395 * A generic {@link Combiner} that lets you use a lambda or method reference to combine two {@link 1396 * ClosingFuture}s. Use {@link #whenAllSucceed(ClosingFuture, ClosingFuture)} to start this 1397 * combination. 1398 * 1399 * @param <V1> the type returned by the first future 1400 * @param <V2> the type returned by the second future 1401 */ 1402 public static final class Combiner2<V1 extends @Nullable Object, V2 extends @Nullable Object> 1403 extends Combiner { 1404 1405 /** 1406 * A function that returns a value when applied to the values of the two futures passed to 1407 * {@link #whenAllSucceed(ClosingFuture, ClosingFuture)}. 1408 * 1409 * @param <V1> the type returned by the first future 1410 * @param <V2> the type returned by the second future 1411 * @param <U> the type returned by the function 1412 */ 1413 @FunctionalInterface 1414 public interface ClosingFunction2< 1415 V1 extends @Nullable Object, V2 extends @Nullable Object, U extends @Nullable Object> { 1416 1417 /** 1418 * Applies this function to two inputs, or throws an exception if unable to do so. 1419 * 1420 * <p>Any objects that are passed to {@link DeferredCloser#eventuallyClose(Object, Executor) 1421 * closer.eventuallyClose()} will be closed when the {@link ClosingFuture} pipeline is done 1422 * (but not before this method completes), even if this method throws or the pipeline is 1423 * cancelled. 1424 */ 1425 @ParametricNullness 1426 U apply(DeferredCloser closer, @ParametricNullness V1 value1, @ParametricNullness V2 value2) 1427 throws Exception; 1428 } 1429 1430 /** 1431 * A function that returns a {@link ClosingFuture} when applied to the values of the two futures 1432 * passed to {@link #whenAllSucceed(ClosingFuture, ClosingFuture)}. 1433 * 1434 * @param <V1> the type returned by the first future 1435 * @param <V2> the type returned by the second future 1436 * @param <U> the type returned by the function 1437 */ 1438 @FunctionalInterface 1439 public interface AsyncClosingFunction2< 1440 V1 extends @Nullable Object, V2 extends @Nullable Object, U extends @Nullable Object> { 1441 1442 /** 1443 * Applies this function to two inputs, or throws an exception if unable to do so. 1444 * 1445 * <p>Any objects that are passed to {@link DeferredCloser#eventuallyClose(Object, Executor) 1446 * closer.eventuallyClose()} will be closed when the {@link ClosingFuture} pipeline is done 1447 * (but not before this method completes), even if this method throws or the pipeline is 1448 * cancelled. 1449 */ 1450 ClosingFuture<U> apply( 1451 DeferredCloser closer, @ParametricNullness V1 value1, @ParametricNullness V2 value2) 1452 throws Exception; 1453 } 1454 1455 private final ClosingFuture<V1> future1; 1456 private final ClosingFuture<V2> future2; 1457 1458 private Combiner2(ClosingFuture<V1> future1, ClosingFuture<V2> future2) { 1459 super(true, ImmutableList.of(future1, future2)); 1460 this.future1 = future1; 1461 this.future2 = future2; 1462 } 1463 1464 /** 1465 * Returns a new {@code ClosingFuture} pipeline step derived from the inputs by applying a 1466 * combining function to their values. The function can use a {@link DeferredCloser} to capture 1467 * objects to be closed when the pipeline is done. 1468 * 1469 * <p>If this combiner was returned by {@link #whenAllSucceed(ClosingFuture, ClosingFuture)} and 1470 * any of the inputs fail, so will the returned step. 1471 * 1472 * <p>If the function throws a {@code CancellationException}, the pipeline will be cancelled. 1473 * 1474 * <p>If the function throws an {@code ExecutionException}, the cause of the thrown {@code 1475 * ExecutionException} will be extracted and used as the failure of the derived step. 1476 */ 1477 public <U extends @Nullable Object> ClosingFuture<U> call( 1478 final ClosingFunction2<V1, V2, U> function, Executor executor) { 1479 return call( 1480 new CombiningCallable<U>() { 1481 @Override 1482 @ParametricNullness 1483 public U call(DeferredCloser closer, Peeker peeker) throws Exception { 1484 return function.apply(closer, peeker.getDone(future1), peeker.getDone(future2)); 1485 } 1486 1487 @Override 1488 public String toString() { 1489 return function.toString(); 1490 } 1491 }, 1492 executor); 1493 } 1494 1495 /** 1496 * Returns a new {@code ClosingFuture} pipeline step derived from the inputs by applying a 1497 * {@code ClosingFuture}-returning function to their values. The function can use a {@link 1498 * DeferredCloser} to capture objects to be closed when the pipeline is done (other than those 1499 * captured by the returned {@link ClosingFuture}). 1500 * 1501 * <p>If this combiner was returned by {@link #whenAllSucceed(ClosingFuture, ClosingFuture)} and 1502 * any of the inputs fail, so will the returned step. 1503 * 1504 * <p>If the function throws a {@code CancellationException}, the pipeline will be cancelled. 1505 * 1506 * <p>If the function throws an {@code ExecutionException}, the cause of the thrown {@code 1507 * ExecutionException} will be extracted and used as the failure of the derived step. 1508 * 1509 * <p>If the function throws any other exception, it will be used as the failure of the derived 1510 * step. 1511 * 1512 * <p>If an exception is thrown after the function creates a {@code ClosingFuture}, then none of 1513 * the closeable objects in that {@code ClosingFuture} will be closed. 1514 * 1515 * <p>Usage guidelines for this method: 1516 * 1517 * <ul> 1518 * <li>Use this method only when calling an API that returns a {@link ListenableFuture} or a 1519 * {@code ClosingFuture}. If possible, prefer calling {@link #call(CombiningCallable, 1520 * Executor)} instead, with a function that returns the next value directly. 1521 * <li>Call {@link DeferredCloser#eventuallyClose(Object, Executor) closer.eventuallyClose()} 1522 * for every closeable object this step creates in order to capture it for later closing. 1523 * <li>Return a {@code ClosingFuture}. To turn a {@link ListenableFuture} into a {@code 1524 * ClosingFuture} call {@link #from(ListenableFuture)}. 1525 * </ul> 1526 * 1527 * <p>The same warnings about doing heavyweight operations within {@link 1528 * ClosingFuture#transformAsync(AsyncClosingFunction, Executor)} apply here. 1529 */ 1530 public <U extends @Nullable Object> ClosingFuture<U> callAsync( 1531 final AsyncClosingFunction2<V1, V2, U> function, Executor executor) { 1532 return callAsync( 1533 new AsyncCombiningCallable<U>() { 1534 @Override 1535 public ClosingFuture<U> call(DeferredCloser closer, Peeker peeker) throws Exception { 1536 return function.apply(closer, peeker.getDone(future1), peeker.getDone(future2)); 1537 } 1538 1539 @Override 1540 public String toString() { 1541 return function.toString(); 1542 } 1543 }, 1544 executor); 1545 } 1546 } 1547 1548 /** 1549 * A generic {@link Combiner} that lets you use a lambda or method reference to combine three 1550 * {@link ClosingFuture}s. Use {@link #whenAllSucceed(ClosingFuture, ClosingFuture, 1551 * ClosingFuture)} to start this combination. 1552 * 1553 * @param <V1> the type returned by the first future 1554 * @param <V2> the type returned by the second future 1555 * @param <V3> the type returned by the third future 1556 */ 1557 public static final class Combiner3< 1558 V1 extends @Nullable Object, V2 extends @Nullable Object, V3 extends @Nullable Object> 1559 extends Combiner { 1560 /** 1561 * A function that returns a value when applied to the values of the three futures passed to 1562 * {@link #whenAllSucceed(ClosingFuture, ClosingFuture, ClosingFuture)}. 1563 * 1564 * @param <V1> the type returned by the first future 1565 * @param <V2> the type returned by the second future 1566 * @param <V3> the type returned by the third future 1567 * @param <U> the type returned by the function 1568 */ 1569 @FunctionalInterface 1570 public interface ClosingFunction3< 1571 V1 extends @Nullable Object, 1572 V2 extends @Nullable Object, 1573 V3 extends @Nullable Object, 1574 U extends @Nullable Object> { 1575 /** 1576 * Applies this function to three inputs, or throws an exception if unable to do so. 1577 * 1578 * <p>Any objects that are passed to {@link DeferredCloser#eventuallyClose(Object, Executor) 1579 * closer.eventuallyClose()} will be closed when the {@link ClosingFuture} pipeline is done 1580 * (but not before this method completes), even if this method throws or the pipeline is 1581 * cancelled. 1582 */ 1583 @ParametricNullness 1584 U apply( 1585 DeferredCloser closer, 1586 @ParametricNullness V1 value1, 1587 @ParametricNullness V2 value2, 1588 @ParametricNullness V3 value3) 1589 throws Exception; 1590 } 1591 1592 /** 1593 * A function that returns a {@link ClosingFuture} when applied to the values of the three 1594 * futures passed to {@link #whenAllSucceed(ClosingFuture, ClosingFuture, ClosingFuture)}. 1595 * 1596 * @param <V1> the type returned by the first future 1597 * @param <V2> the type returned by the second future 1598 * @param <V3> the type returned by the third future 1599 * @param <U> the type returned by the function 1600 */ 1601 @FunctionalInterface 1602 public interface AsyncClosingFunction3< 1603 V1 extends @Nullable Object, 1604 V2 extends @Nullable Object, 1605 V3 extends @Nullable Object, 1606 U extends @Nullable Object> { 1607 /** 1608 * Applies this function to three inputs, or throws an exception if unable to do so. 1609 * 1610 * <p>Any objects that are passed to {@link DeferredCloser#eventuallyClose(Object, Executor) 1611 * closer.eventuallyClose()} will be closed when the {@link ClosingFuture} pipeline is done 1612 * (but not before this method completes), even if this method throws or the pipeline is 1613 * cancelled. 1614 */ 1615 ClosingFuture<U> apply( 1616 DeferredCloser closer, 1617 @ParametricNullness V1 value1, 1618 @ParametricNullness V2 value2, 1619 @ParametricNullness V3 value3) 1620 throws Exception; 1621 } 1622 1623 private final ClosingFuture<V1> future1; 1624 private final ClosingFuture<V2> future2; 1625 private final ClosingFuture<V3> future3; 1626 1627 private Combiner3( 1628 ClosingFuture<V1> future1, ClosingFuture<V2> future2, ClosingFuture<V3> future3) { 1629 super(true, ImmutableList.of(future1, future2, future3)); 1630 this.future1 = future1; 1631 this.future2 = future2; 1632 this.future3 = future3; 1633 } 1634 1635 /** 1636 * Returns a new {@code ClosingFuture} pipeline step derived from the inputs by applying a 1637 * combining function to their values. The function can use a {@link DeferredCloser} to capture 1638 * objects to be closed when the pipeline is done. 1639 * 1640 * <p>If this combiner was returned by {@link #whenAllSucceed(ClosingFuture, ClosingFuture, 1641 * ClosingFuture)} and any of the inputs fail, so will the returned step. 1642 * 1643 * <p>If the function throws a {@code CancellationException}, the pipeline will be cancelled. 1644 * 1645 * <p>If the function throws an {@code ExecutionException}, the cause of the thrown {@code 1646 * ExecutionException} will be extracted and used as the failure of the derived step. 1647 */ 1648 public <U extends @Nullable Object> ClosingFuture<U> call( 1649 final ClosingFunction3<V1, V2, V3, U> function, Executor executor) { 1650 return call( 1651 new CombiningCallable<U>() { 1652 @Override 1653 @ParametricNullness 1654 public U call(DeferredCloser closer, Peeker peeker) throws Exception { 1655 return function.apply( 1656 closer, 1657 peeker.getDone(future1), 1658 peeker.getDone(future2), 1659 peeker.getDone(future3)); 1660 } 1661 1662 @Override 1663 public String toString() { 1664 return function.toString(); 1665 } 1666 }, 1667 executor); 1668 } 1669 1670 /** 1671 * Returns a new {@code ClosingFuture} pipeline step derived from the inputs by applying a 1672 * {@code ClosingFuture}-returning function to their values. The function can use a {@link 1673 * DeferredCloser} to capture objects to be closed when the pipeline is done (other than those 1674 * captured by the returned {@link ClosingFuture}). 1675 * 1676 * <p>If this combiner was returned by {@link #whenAllSucceed(ClosingFuture, ClosingFuture, 1677 * ClosingFuture)} and any of the inputs fail, so will the returned step. 1678 * 1679 * <p>If the function throws a {@code CancellationException}, the pipeline will be cancelled. 1680 * 1681 * <p>If the function throws an {@code ExecutionException}, the cause of the thrown {@code 1682 * ExecutionException} will be extracted and used as the failure of the derived step. 1683 * 1684 * <p>If the function throws any other exception, it will be used as the failure of the derived 1685 * step. 1686 * 1687 * <p>If an exception is thrown after the function creates a {@code ClosingFuture}, then none of 1688 * the closeable objects in that {@code ClosingFuture} will be closed. 1689 * 1690 * <p>Usage guidelines for this method: 1691 * 1692 * <ul> 1693 * <li>Use this method only when calling an API that returns a {@link ListenableFuture} or a 1694 * {@code ClosingFuture}. If possible, prefer calling {@link #call(CombiningCallable, 1695 * Executor)} instead, with a function that returns the next value directly. 1696 * <li>Call {@link DeferredCloser#eventuallyClose(Object, Executor) closer.eventuallyClose()} 1697 * for every closeable object this step creates in order to capture it for later closing. 1698 * <li>Return a {@code ClosingFuture}. To turn a {@link ListenableFuture} into a {@code 1699 * ClosingFuture} call {@link #from(ListenableFuture)}. 1700 * </ul> 1701 * 1702 * <p>The same warnings about doing heavyweight operations within {@link 1703 * ClosingFuture#transformAsync(AsyncClosingFunction, Executor)} apply here. 1704 */ 1705 public <U extends @Nullable Object> ClosingFuture<U> callAsync( 1706 final AsyncClosingFunction3<V1, V2, V3, U> function, Executor executor) { 1707 return callAsync( 1708 new AsyncCombiningCallable<U>() { 1709 @Override 1710 public ClosingFuture<U> call(DeferredCloser closer, Peeker peeker) throws Exception { 1711 return function.apply( 1712 closer, 1713 peeker.getDone(future1), 1714 peeker.getDone(future2), 1715 peeker.getDone(future3)); 1716 } 1717 1718 @Override 1719 public String toString() { 1720 return function.toString(); 1721 } 1722 }, 1723 executor); 1724 } 1725 } 1726 1727 /** 1728 * A generic {@link Combiner} that lets you use a lambda or method reference to combine four 1729 * {@link ClosingFuture}s. Use {@link #whenAllSucceed(ClosingFuture, ClosingFuture, ClosingFuture, 1730 * ClosingFuture)} to start this combination. 1731 * 1732 * @param <V1> the type returned by the first future 1733 * @param <V2> the type returned by the second future 1734 * @param <V3> the type returned by the third future 1735 * @param <V4> the type returned by the fourth future 1736 */ 1737 public static final class Combiner4< 1738 V1 extends @Nullable Object, 1739 V2 extends @Nullable Object, 1740 V3 extends @Nullable Object, 1741 V4 extends @Nullable Object> 1742 extends Combiner { 1743 /** 1744 * A function that returns a value when applied to the values of the four futures passed to 1745 * {@link #whenAllSucceed(ClosingFuture, ClosingFuture, ClosingFuture, ClosingFuture)}. 1746 * 1747 * @param <V1> the type returned by the first future 1748 * @param <V2> the type returned by the second future 1749 * @param <V3> the type returned by the third future 1750 * @param <V4> the type returned by the fourth future 1751 * @param <U> the type returned by the function 1752 */ 1753 @FunctionalInterface 1754 public interface ClosingFunction4< 1755 V1 extends @Nullable Object, 1756 V2 extends @Nullable Object, 1757 V3 extends @Nullable Object, 1758 V4 extends @Nullable Object, 1759 U extends @Nullable Object> { 1760 /** 1761 * Applies this function to four inputs, or throws an exception if unable to do so. 1762 * 1763 * <p>Any objects that are passed to {@link DeferredCloser#eventuallyClose(Object, Executor) 1764 * closer.eventuallyClose()} will be closed when the {@link ClosingFuture} pipeline is done 1765 * (but not before this method completes), even if this method throws or the pipeline is 1766 * cancelled. 1767 */ 1768 @ParametricNullness 1769 U apply( 1770 DeferredCloser closer, 1771 @ParametricNullness V1 value1, 1772 @ParametricNullness V2 value2, 1773 @ParametricNullness V3 value3, 1774 @ParametricNullness V4 value4) 1775 throws Exception; 1776 } 1777 1778 /** 1779 * A function that returns a {@link ClosingFuture} when applied to the values of the four 1780 * futures passed to {@link #whenAllSucceed(ClosingFuture, ClosingFuture, ClosingFuture, 1781 * ClosingFuture)}. 1782 * 1783 * @param <V1> the type returned by the first future 1784 * @param <V2> the type returned by the second future 1785 * @param <V3> the type returned by the third future 1786 * @param <V4> the type returned by the fourth future 1787 * @param <U> the type returned by the function 1788 */ 1789 @FunctionalInterface 1790 public interface AsyncClosingFunction4< 1791 V1 extends @Nullable Object, 1792 V2 extends @Nullable Object, 1793 V3 extends @Nullable Object, 1794 V4 extends @Nullable Object, 1795 U extends @Nullable Object> { 1796 /** 1797 * Applies this function to four inputs, or throws an exception if unable to do so. 1798 * 1799 * <p>Any objects that are passed to {@link DeferredCloser#eventuallyClose(Object, Executor) 1800 * closer.eventuallyClose()} will be closed when the {@link ClosingFuture} pipeline is done 1801 * (but not before this method completes), even if this method throws or the pipeline is 1802 * cancelled. 1803 */ 1804 ClosingFuture<U> apply( 1805 DeferredCloser closer, 1806 @ParametricNullness V1 value1, 1807 @ParametricNullness V2 value2, 1808 @ParametricNullness V3 value3, 1809 @ParametricNullness V4 value4) 1810 throws Exception; 1811 } 1812 1813 private final ClosingFuture<V1> future1; 1814 private final ClosingFuture<V2> future2; 1815 private final ClosingFuture<V3> future3; 1816 private final ClosingFuture<V4> future4; 1817 1818 private Combiner4( 1819 ClosingFuture<V1> future1, 1820 ClosingFuture<V2> future2, 1821 ClosingFuture<V3> future3, 1822 ClosingFuture<V4> future4) { 1823 super(true, ImmutableList.of(future1, future2, future3, future4)); 1824 this.future1 = future1; 1825 this.future2 = future2; 1826 this.future3 = future3; 1827 this.future4 = future4; 1828 } 1829 1830 /** 1831 * Returns a new {@code ClosingFuture} pipeline step derived from the inputs by applying a 1832 * combining function to their values. The function can use a {@link DeferredCloser} to capture 1833 * objects to be closed when the pipeline is done. 1834 * 1835 * <p>If this combiner was returned by {@link #whenAllSucceed(ClosingFuture, ClosingFuture, 1836 * ClosingFuture, ClosingFuture)} and any of the inputs fail, so will the returned step. 1837 * 1838 * <p>If the function throws a {@code CancellationException}, the pipeline will be cancelled. 1839 * 1840 * <p>If the function throws an {@code ExecutionException}, the cause of the thrown {@code 1841 * ExecutionException} will be extracted and used as the failure of the derived step. 1842 */ 1843 public <U extends @Nullable Object> ClosingFuture<U> call( 1844 final ClosingFunction4<V1, V2, V3, V4, U> function, Executor executor) { 1845 return call( 1846 new CombiningCallable<U>() { 1847 @Override 1848 @ParametricNullness 1849 public U call(DeferredCloser closer, Peeker peeker) throws Exception { 1850 return function.apply( 1851 closer, 1852 peeker.getDone(future1), 1853 peeker.getDone(future2), 1854 peeker.getDone(future3), 1855 peeker.getDone(future4)); 1856 } 1857 1858 @Override 1859 public String toString() { 1860 return function.toString(); 1861 } 1862 }, 1863 executor); 1864 } 1865 1866 /** 1867 * Returns a new {@code ClosingFuture} pipeline step derived from the inputs by applying a 1868 * {@code ClosingFuture}-returning function to their values. The function can use a {@link 1869 * DeferredCloser} to capture objects to be closed when the pipeline is done (other than those 1870 * captured by the returned {@link ClosingFuture}). 1871 * 1872 * <p>If this combiner was returned by {@link #whenAllSucceed(ClosingFuture, ClosingFuture, 1873 * ClosingFuture, ClosingFuture)} and any of the inputs fail, so will the returned step. 1874 * 1875 * <p>If the function throws a {@code CancellationException}, the pipeline will be cancelled. 1876 * 1877 * <p>If the function throws an {@code ExecutionException}, the cause of the thrown {@code 1878 * ExecutionException} will be extracted and used as the failure of the derived step. 1879 * 1880 * <p>If the function throws any other exception, it will be used as the failure of the derived 1881 * step. 1882 * 1883 * <p>If an exception is thrown after the function creates a {@code ClosingFuture}, then none of 1884 * the closeable objects in that {@code ClosingFuture} will be closed. 1885 * 1886 * <p>Usage guidelines for this method: 1887 * 1888 * <ul> 1889 * <li>Use this method only when calling an API that returns a {@link ListenableFuture} or a 1890 * {@code ClosingFuture}. If possible, prefer calling {@link #call(CombiningCallable, 1891 * Executor)} instead, with a function that returns the next value directly. 1892 * <li>Call {@link DeferredCloser#eventuallyClose(Object, Executor) closer.eventuallyClose()} 1893 * for every closeable object this step creates in order to capture it for later closing. 1894 * <li>Return a {@code ClosingFuture}. To turn a {@link ListenableFuture} into a {@code 1895 * ClosingFuture} call {@link #from(ListenableFuture)}. 1896 * </ul> 1897 * 1898 * <p>The same warnings about doing heavyweight operations within {@link 1899 * ClosingFuture#transformAsync(AsyncClosingFunction, Executor)} apply here. 1900 */ 1901 public <U extends @Nullable Object> ClosingFuture<U> callAsync( 1902 final AsyncClosingFunction4<V1, V2, V3, V4, U> function, Executor executor) { 1903 return callAsync( 1904 new AsyncCombiningCallable<U>() { 1905 @Override 1906 public ClosingFuture<U> call(DeferredCloser closer, Peeker peeker) throws Exception { 1907 return function.apply( 1908 closer, 1909 peeker.getDone(future1), 1910 peeker.getDone(future2), 1911 peeker.getDone(future3), 1912 peeker.getDone(future4)); 1913 } 1914 1915 @Override 1916 public String toString() { 1917 return function.toString(); 1918 } 1919 }, 1920 executor); 1921 } 1922 } 1923 1924 /** 1925 * A generic {@link Combiner} that lets you use a lambda or method reference to combine five 1926 * {@link ClosingFuture}s. Use {@link #whenAllSucceed(ClosingFuture, ClosingFuture, ClosingFuture, 1927 * ClosingFuture, ClosingFuture)} to start this combination. 1928 * 1929 * @param <V1> the type returned by the first future 1930 * @param <V2> the type returned by the second future 1931 * @param <V3> the type returned by the third future 1932 * @param <V4> the type returned by the fourth future 1933 * @param <V5> the type returned by the fifth future 1934 */ 1935 public static final class Combiner5< 1936 V1 extends @Nullable Object, 1937 V2 extends @Nullable Object, 1938 V3 extends @Nullable Object, 1939 V4 extends @Nullable Object, 1940 V5 extends @Nullable Object> 1941 extends Combiner { 1942 /** 1943 * A function that returns a value when applied to the values of the five futures passed to 1944 * {@link #whenAllSucceed(ClosingFuture, ClosingFuture, ClosingFuture, ClosingFuture, 1945 * ClosingFuture)}. 1946 * 1947 * @param <V1> the type returned by the first future 1948 * @param <V2> the type returned by the second future 1949 * @param <V3> the type returned by the third future 1950 * @param <V4> the type returned by the fourth future 1951 * @param <V5> the type returned by the fifth future 1952 * @param <U> the type returned by the function 1953 */ 1954 @FunctionalInterface 1955 public interface ClosingFunction5< 1956 V1 extends @Nullable Object, 1957 V2 extends @Nullable Object, 1958 V3 extends @Nullable Object, 1959 V4 extends @Nullable Object, 1960 V5 extends @Nullable Object, 1961 U extends @Nullable Object> { 1962 /** 1963 * Applies this function to five inputs, or throws an exception if unable to do so. 1964 * 1965 * <p>Any objects that are passed to {@link DeferredCloser#eventuallyClose(Object, Executor) 1966 * closer.eventuallyClose()} will be closed when the {@link ClosingFuture} pipeline is done 1967 * (but not before this method completes), even if this method throws or the pipeline is 1968 * cancelled. 1969 */ 1970 @ParametricNullness 1971 U apply( 1972 DeferredCloser closer, 1973 @ParametricNullness V1 value1, 1974 @ParametricNullness V2 value2, 1975 @ParametricNullness V3 value3, 1976 @ParametricNullness V4 value4, 1977 @ParametricNullness V5 value5) 1978 throws Exception; 1979 } 1980 1981 /** 1982 * A function that returns a {@link ClosingFuture} when applied to the values of the five 1983 * futures passed to {@link #whenAllSucceed(ClosingFuture, ClosingFuture, ClosingFuture, 1984 * ClosingFuture, ClosingFuture)}. 1985 * 1986 * @param <V1> the type returned by the first future 1987 * @param <V2> the type returned by the second future 1988 * @param <V3> the type returned by the third future 1989 * @param <V4> the type returned by the fourth future 1990 * @param <V5> the type returned by the fifth future 1991 * @param <U> the type returned by the function 1992 */ 1993 @FunctionalInterface 1994 public interface AsyncClosingFunction5< 1995 V1 extends @Nullable Object, 1996 V2 extends @Nullable Object, 1997 V3 extends @Nullable Object, 1998 V4 extends @Nullable Object, 1999 V5 extends @Nullable Object, 2000 U extends @Nullable Object> { 2001 /** 2002 * Applies this function to five inputs, or throws an exception if unable to do so. 2003 * 2004 * <p>Any objects that are passed to {@link DeferredCloser#eventuallyClose(Object, Executor) 2005 * closer.eventuallyClose()} will be closed when the {@link ClosingFuture} pipeline is done 2006 * (but not before this method completes), even if this method throws or the pipeline is 2007 * cancelled. 2008 */ 2009 ClosingFuture<U> apply( 2010 DeferredCloser closer, 2011 @ParametricNullness V1 value1, 2012 @ParametricNullness V2 value2, 2013 @ParametricNullness V3 value3, 2014 @ParametricNullness V4 value4, 2015 @ParametricNullness V5 value5) 2016 throws Exception; 2017 } 2018 2019 private final ClosingFuture<V1> future1; 2020 private final ClosingFuture<V2> future2; 2021 private final ClosingFuture<V3> future3; 2022 private final ClosingFuture<V4> future4; 2023 private final ClosingFuture<V5> future5; 2024 2025 private Combiner5( 2026 ClosingFuture<V1> future1, 2027 ClosingFuture<V2> future2, 2028 ClosingFuture<V3> future3, 2029 ClosingFuture<V4> future4, 2030 ClosingFuture<V5> future5) { 2031 super(true, ImmutableList.of(future1, future2, future3, future4, future5)); 2032 this.future1 = future1; 2033 this.future2 = future2; 2034 this.future3 = future3; 2035 this.future4 = future4; 2036 this.future5 = future5; 2037 } 2038 2039 /** 2040 * Returns a new {@code ClosingFuture} pipeline step derived from the inputs by applying a 2041 * combining function to their values. The function can use a {@link DeferredCloser} to capture 2042 * objects to be closed when the pipeline is done. 2043 * 2044 * <p>If this combiner was returned by {@link #whenAllSucceed(ClosingFuture, ClosingFuture, 2045 * ClosingFuture, ClosingFuture, ClosingFuture)} and any of the inputs fail, so will the 2046 * returned step. 2047 * 2048 * <p>If the function throws a {@code CancellationException}, the pipeline will be cancelled. 2049 * 2050 * <p>If the function throws an {@code ExecutionException}, the cause of the thrown {@code 2051 * ExecutionException} will be extracted and used as the failure of the derived step. 2052 */ 2053 public <U extends @Nullable Object> ClosingFuture<U> call( 2054 final ClosingFunction5<V1, V2, V3, V4, V5, U> function, Executor executor) { 2055 return call( 2056 new CombiningCallable<U>() { 2057 @Override 2058 @ParametricNullness 2059 public U call(DeferredCloser closer, Peeker peeker) throws Exception { 2060 return function.apply( 2061 closer, 2062 peeker.getDone(future1), 2063 peeker.getDone(future2), 2064 peeker.getDone(future3), 2065 peeker.getDone(future4), 2066 peeker.getDone(future5)); 2067 } 2068 2069 @Override 2070 public String toString() { 2071 return function.toString(); 2072 } 2073 }, 2074 executor); 2075 } 2076 2077 /** 2078 * Returns a new {@code ClosingFuture} pipeline step derived from the inputs by applying a 2079 * {@code ClosingFuture}-returning function to their values. The function can use a {@link 2080 * DeferredCloser} to capture objects to be closed when the pipeline is done (other than those 2081 * captured by the returned {@link ClosingFuture}). 2082 * 2083 * <p>If this combiner was returned by {@link #whenAllSucceed(ClosingFuture, ClosingFuture, 2084 * ClosingFuture, ClosingFuture, ClosingFuture)} and any of the inputs fail, so will the 2085 * returned step. 2086 * 2087 * <p>If the function throws a {@code CancellationException}, the pipeline will be cancelled. 2088 * 2089 * <p>If the function throws an {@code ExecutionException}, the cause of the thrown {@code 2090 * ExecutionException} will be extracted and used as the failure of the derived step. 2091 * 2092 * <p>If the function throws any other exception, it will be used as the failure of the derived 2093 * step. 2094 * 2095 * <p>If an exception is thrown after the function creates a {@code ClosingFuture}, then none of 2096 * the closeable objects in that {@code ClosingFuture} will be closed. 2097 * 2098 * <p>Usage guidelines for this method: 2099 * 2100 * <ul> 2101 * <li>Use this method only when calling an API that returns a {@link ListenableFuture} or a 2102 * {@code ClosingFuture}. If possible, prefer calling {@link #call(CombiningCallable, 2103 * Executor)} instead, with a function that returns the next value directly. 2104 * <li>Call {@link DeferredCloser#eventuallyClose(Object, Executor) closer.eventuallyClose()} 2105 * for every closeable object this step creates in order to capture it for later closing. 2106 * <li>Return a {@code ClosingFuture}. To turn a {@link ListenableFuture} into a {@code 2107 * ClosingFuture} call {@link #from(ListenableFuture)}. 2108 * </ul> 2109 * 2110 * <p>The same warnings about doing heavyweight operations within {@link 2111 * ClosingFuture#transformAsync(AsyncClosingFunction, Executor)} apply here. 2112 */ 2113 public <U extends @Nullable Object> ClosingFuture<U> callAsync( 2114 final AsyncClosingFunction5<V1, V2, V3, V4, V5, U> function, Executor executor) { 2115 return callAsync( 2116 new AsyncCombiningCallable<U>() { 2117 @Override 2118 public ClosingFuture<U> call(DeferredCloser closer, Peeker peeker) throws Exception { 2119 return function.apply( 2120 closer, 2121 peeker.getDone(future1), 2122 peeker.getDone(future2), 2123 peeker.getDone(future3), 2124 peeker.getDone(future4), 2125 peeker.getDone(future5)); 2126 } 2127 2128 @Override 2129 public String toString() { 2130 return function.toString(); 2131 } 2132 }, 2133 executor); 2134 } 2135 } 2136 2137 @Override 2138 public String toString() { 2139 // TODO(dpb): Better toString, in the style of Futures.transform etc. 2140 return toStringHelper(this).add("state", state.get()).addValue(future).toString(); 2141 } 2142 2143 @SuppressWarnings("removal") // b/260137033 2144 @Override 2145 protected void finalize() { 2146 if (state.get().equals(OPEN)) { 2147 logger.get().log(SEVERE, "Uh oh! An open ClosingFuture has leaked and will close: {0}", this); 2148 FluentFuture<V> unused = finishToFuture(); 2149 } 2150 } 2151 2152 private static void closeQuietly(@CheckForNull final AutoCloseable closeable, Executor executor) { 2153 if (closeable == null) { 2154 return; 2155 } 2156 try { 2157 executor.execute( 2158 () -> { 2159 try { 2160 closeable.close(); 2161 } catch (Exception e) { 2162 /* 2163 * In guava-jre, any kind of Exception may be thrown because `closeable` has type 2164 * `AutoCloseable`. 2165 * 2166 * In guava-android, the only kinds of Exception that may be thrown are 2167 * RuntimeException and IOException because `closeable` has type `Closeable`—except 2168 * that we have to account for sneaky checked exception. 2169 */ 2170 restoreInterruptIfIsInterruptedException(e); 2171 logger.get().log(WARNING, "thrown by close()", e); 2172 } 2173 }); 2174 } catch (RejectedExecutionException e) { 2175 if (logger.get().isLoggable(WARNING)) { 2176 logger 2177 .get() 2178 .log( 2179 WARNING, 2180 String.format("while submitting close to %s; will close inline", executor), 2181 e); 2182 } 2183 closeQuietly(closeable, directExecutor()); 2184 } 2185 } 2186 2187 private void checkAndUpdateState(State oldState, State newState) { 2188 checkState( 2189 compareAndUpdateState(oldState, newState), 2190 "Expected state to be %s, but it was %s", 2191 oldState, 2192 newState); 2193 } 2194 2195 private boolean compareAndUpdateState(State oldState, State newState) { 2196 return state.compareAndSet(oldState, newState); 2197 } 2198 2199 // TODO(dpb): Should we use a pair of ArrayLists instead of an IdentityHashMap? 2200 private static final class CloseableList extends IdentityHashMap<AutoCloseable, Executor> 2201 implements Closeable { 2202 private final DeferredCloser closer = new DeferredCloser(this); 2203 private volatile boolean closed; 2204 @CheckForNull private volatile CountDownLatch whenClosed; 2205 2206 <V extends @Nullable Object, U extends @Nullable Object> 2207 ListenableFuture<U> applyClosingFunction( 2208 ClosingFunction<? super V, U> transformation, @ParametricNullness V input) 2209 throws Exception { 2210 // TODO(dpb): Consider ways to defer closing without creating a separate CloseableList. 2211 CloseableList newCloseables = new CloseableList(); 2212 try { 2213 return immediateFuture(transformation.apply(newCloseables.closer, input)); 2214 } finally { 2215 add(newCloseables, directExecutor()); 2216 } 2217 } 2218 2219 <V extends @Nullable Object, U extends @Nullable Object> 2220 FluentFuture<U> applyAsyncClosingFunction( 2221 AsyncClosingFunction<V, U> transformation, @ParametricNullness V input) 2222 throws Exception { 2223 // TODO(dpb): Consider ways to defer closing without creating a separate CloseableList. 2224 CloseableList newCloseables = new CloseableList(); 2225 try { 2226 ClosingFuture<U> closingFuture = transformation.apply(newCloseables.closer, input); 2227 closingFuture.becomeSubsumedInto(newCloseables); 2228 return closingFuture.future; 2229 } finally { 2230 add(newCloseables, directExecutor()); 2231 } 2232 } 2233 2234 @Override 2235 public void close() { 2236 if (closed) { 2237 return; 2238 } 2239 synchronized (this) { 2240 if (closed) { 2241 return; 2242 } 2243 closed = true; 2244 } 2245 for (Map.Entry<AutoCloseable, Executor> entry : entrySet()) { 2246 closeQuietly(entry.getKey(), entry.getValue()); 2247 } 2248 clear(); 2249 if (whenClosed != null) { 2250 whenClosed.countDown(); 2251 } 2252 } 2253 2254 void add(@CheckForNull AutoCloseable closeable, Executor executor) { 2255 checkNotNull(executor); 2256 if (closeable == null) { 2257 return; 2258 } 2259 synchronized (this) { 2260 if (!closed) { 2261 put(closeable, executor); 2262 return; 2263 } 2264 } 2265 closeQuietly(closeable, executor); 2266 } 2267 2268 /** 2269 * Returns a latch that reaches zero when this objects' deferred closeables have been closed. 2270 */ 2271 CountDownLatch whenClosedCountDown() { 2272 if (closed) { 2273 return new CountDownLatch(0); 2274 } 2275 synchronized (this) { 2276 if (closed) { 2277 return new CountDownLatch(0); 2278 } 2279 checkState(whenClosed == null); 2280 return whenClosed = new CountDownLatch(1); 2281 } 2282 } 2283 } 2284 2285 /** 2286 * Returns an object that can be used to wait until this objects' deferred closeables have all had 2287 * {@link Runnable}s that close them submitted to each one's closing {@link Executor}. 2288 */ 2289 @VisibleForTesting 2290 CountDownLatch whenClosedCountDown() { 2291 return closeables.whenClosedCountDown(); 2292 } 2293 2294 /** The state of a {@link CloseableList}. */ 2295 enum State { 2296 /** The {@link CloseableList} has not been subsumed or closed. */ 2297 OPEN, 2298 2299 /** 2300 * The {@link CloseableList} has been subsumed into another. It may not be closed or subsumed 2301 * into any other. 2302 */ 2303 SUBSUMED, 2304 2305 /** 2306 * Some {@link ListenableFuture} has a callback attached that will close the {@link 2307 * CloseableList}, but it has not yet run. The {@link CloseableList} may not be subsumed. 2308 */ 2309 WILL_CLOSE, 2310 2311 /** 2312 * The callback that closes the {@link CloseableList} is running, but it has not completed. The 2313 * {@link CloseableList} may not be subsumed. 2314 */ 2315 CLOSING, 2316 2317 /** The {@link CloseableList} has been closed. It may not be further subsumed. */ 2318 CLOSED, 2319 2320 /** 2321 * {@link ClosingFuture#finishToValueAndCloser(ValueAndCloserConsumer, Executor)} has been 2322 * called. The step may not be further subsumed, nor may {@link #finishToFuture()} be called. 2323 */ 2324 WILL_CREATE_VALUE_AND_CLOSER, 2325 } 2326}