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.VisibleForTesting; 041import com.google.common.base.Function; 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 java.util.logging.Logger; 062import javax.annotation.CheckForNull; 063import org.checkerframework.checker.nullness.qual.Nullable; 064 065/** 066 * A step in a pipeline of an asynchronous computation. When the last step in the computation is 067 * complete, some objects captured during the computation are closed. 068 * 069 * <p>A pipeline of {@code ClosingFuture}s is a tree of steps. Each step represents either an 070 * asynchronously-computed intermediate value, or else an exception that indicates the failure or 071 * cancellation of the operation so far. The only way to extract the value or exception from a step 072 * is by declaring that step to be the last step of the pipeline. Nevertheless, we refer to the 073 * "value" of a successful step or the "result" (value or exception) of any step. 074 * 075 * <ol> 076 * <li>A pipeline starts at its leaf step (or steps), which is created from either a callable 077 * block or a {@link ListenableFuture}. 078 * <li>Each other step is derived from one or more input steps. At each step, zero or more objects 079 * can be captured for later closing. 080 * <li>There is one last step (the root of the tree), from which you can extract the final result 081 * of the computation. After that result is available (or the computation fails), all objects 082 * captured by any of the steps in the pipeline are closed. 083 * </ol> 084 * 085 * <h3>Starting a pipeline</h3> 086 * 087 * Start a {@code ClosingFuture} pipeline {@linkplain #submit(ClosingCallable, Executor) from a 088 * callable block} that may capture objects for later closing. To start a pipeline from a {@link 089 * ListenableFuture} that doesn't create resources that should be closed later, you can use {@link 090 * #from(ListenableFuture)} instead. 091 * 092 * <h3>Derived steps</h3> 093 * 094 * A {@code ClosingFuture} step can be derived from one or more input {@code ClosingFuture} steps in 095 * ways similar to {@link FluentFuture}s: 096 * 097 * <ul> 098 * <li>by transforming the value from a successful input step, 099 * <li>by catching the exception from a failed input step, or 100 * <li>by combining the results of several input steps. 101 * </ul> 102 * 103 * Each derivation can capture the next value or any intermediate objects for later closing. 104 * 105 * <p>A step can be the input to at most one derived step. Once you transform its value, catch its 106 * exception, or combine it with others, you cannot do anything else with it, including declare it 107 * to be the last step of the pipeline. 108 * 109 * <h4>Transforming</h4> 110 * 111 * To derive the next step by asynchronously applying a function to an input step's value, call 112 * {@link #transform(ClosingFunction, Executor)} or {@link #transformAsync(AsyncClosingFunction, 113 * Executor)} on the input step. 114 * 115 * <h4>Catching</h4> 116 * 117 * To derive the next step from a failed input step, call {@link #catching(Class, ClosingFunction, 118 * Executor)} or {@link #catchingAsync(Class, AsyncClosingFunction, Executor)} on the input step. 119 * 120 * <h4>Combining</h4> 121 * 122 * To derive a {@code ClosingFuture} from two or more input steps, pass the input steps to {@link 123 * #whenAllComplete(Iterable)} or {@link #whenAllSucceed(Iterable)} or its overloads. 124 * 125 * <h3>Cancelling</h3> 126 * 127 * Any step in a pipeline can be {@linkplain #cancel(boolean) cancelled}, even after another step 128 * has been derived, with the same semantics as cancelling a {@link Future}. In addition, a 129 * successfully cancelled step will immediately start closing all objects captured for later closing 130 * by it and by its input steps. 131 * 132 * <h3>Ending a pipeline</h3> 133 * 134 * Each {@code ClosingFuture} pipeline must be ended. To end a pipeline, decide whether you want to 135 * close the captured objects automatically or manually. 136 * 137 * <h4>Automatically closing</h4> 138 * 139 * You can extract a {@link Future} that represents the result of the last step in the pipeline by 140 * calling {@link #finishToFuture()}. All objects the pipeline has captured for closing will begin 141 * to be closed asynchronously <b>after</b> the returned {@code Future} is done: the future 142 * completes before closing starts, rather than once it has finished. 143 * 144 * <pre>{@code 145 * FluentFuture<UserName> userName = 146 * ClosingFuture.submit( 147 * closer -> closer.eventuallyClose(database.newTransaction(), closingExecutor), 148 * executor) 149 * .transformAsync((closer, transaction) -> transaction.queryClosingFuture("..."), executor) 150 * .transform((closer, result) -> result.get("userName"), directExecutor()) 151 * .catching(DBException.class, e -> "no user", directExecutor()) 152 * .finishToFuture(); 153 * }</pre> 154 * 155 * In this example, when the {@code userName} {@link Future} is done, the transaction and the query 156 * result cursor will both be closed, even if the operation is cancelled or fails. 157 * 158 * <h4>Manually closing</h4> 159 * 160 * If you want to close the captured objects manually, after you've used the final result, call 161 * {@link #finishToValueAndCloser(ValueAndCloserConsumer, Executor)} to get an object that holds the 162 * final result. You then call {@link ValueAndCloser#closeAsync()} to close the captured objects. 163 * 164 * <pre>{@code 165 * ClosingFuture.submit( 166 * closer -> closer.eventuallyClose(database.newTransaction(), closingExecutor), 167 * executor) 168 * .transformAsync((closer, transaction) -> transaction.queryClosingFuture("..."), executor) 169 * .transform((closer, result) -> result.get("userName"), directExecutor()) 170 * .catching(DBException.class, e -> "no user", directExecutor()) 171 * .finishToValueAndCloser( 172 * valueAndCloser -> this.userNameValueAndCloser = valueAndCloser, executor); 173 * 174 * // later 175 * try { // get() will throw if the operation failed or was cancelled. 176 * UserName userName = userNameValueAndCloser.get(); 177 * // do something with userName 178 * } finally { 179 * userNameValueAndCloser.closeAsync(); 180 * } 181 * }</pre> 182 * 183 * In this example, when {@code userNameValueAndCloser.closeAsync()} is called, the transaction and 184 * the query result cursor will both be closed, even if the operation is cancelled or fails. 185 * 186 * <p>Note that if you don't call {@code closeAsync()}, the captured objects will not be closed. The 187 * automatic-closing approach described above is safer. 188 * 189 * @param <V> the type of the value of this step 190 * @since 30.0 191 */ 192// TODO(dpb): Consider reusing one CloseableList for the entire pipeline, modulo combinations. 193@DoNotMock("Use ClosingFuture.from(Futures.immediate*Future)") 194@ElementTypesAreNonnullByDefault 195// TODO(dpb): GWT compatibility. 196public final class ClosingFuture<V extends @Nullable Object> { 197 198 private static final Logger logger = Logger.getLogger(ClosingFuture.class.getName()); 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 * this {@code ClosingFuture}. 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 * this {@code ClosingFuture}. 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 * this {@code ClosingFuture}. 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 * this {@code ClosingFuture}. 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 this {@code ClosingFuture}. 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.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 this {@code ClosingFuture}. 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.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.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 private static final Function<ClosingFuture<?>, FluentFuture<?>> INNER_FUTURE = 1387 new Function<ClosingFuture<?>, FluentFuture<?>>() { 1388 @Override 1389 public FluentFuture<?> apply(ClosingFuture<?> future) { 1390 return future.future; 1391 } 1392 }; 1393 1394 private ImmutableList<FluentFuture<?>> inputFutures() { 1395 return FluentIterable.from(inputs).transform(INNER_FUTURE).toList(); 1396 } 1397 } 1398 1399 /** 1400 * A generic {@link Combiner} that lets you use a lambda or method reference to combine two {@link 1401 * ClosingFuture}s. Use {@link #whenAllSucceed(ClosingFuture, ClosingFuture)} to start this 1402 * combination. 1403 * 1404 * @param <V1> the type returned by the first future 1405 * @param <V2> the type returned by the second future 1406 */ 1407 public static final class Combiner2<V1 extends @Nullable Object, V2 extends @Nullable Object> 1408 extends Combiner { 1409 1410 /** 1411 * A function that returns a value when applied to the values of the two futures passed to 1412 * {@link #whenAllSucceed(ClosingFuture, ClosingFuture)}. 1413 * 1414 * @param <V1> the type returned by the first future 1415 * @param <V2> the type returned by the second future 1416 * @param <U> the type returned by the function 1417 */ 1418 @FunctionalInterface 1419 public interface ClosingFunction2< 1420 V1 extends @Nullable Object, V2 extends @Nullable Object, U extends @Nullable Object> { 1421 1422 /** 1423 * Applies this function to two inputs, or throws an exception if unable to do so. 1424 * 1425 * <p>Any objects that are passed to {@link DeferredCloser#eventuallyClose(Object, Executor) 1426 * closer.eventuallyClose()} will be closed when the {@link ClosingFuture} pipeline is done 1427 * (but not before this method completes), even if this method throws or the pipeline is 1428 * cancelled. 1429 */ 1430 @ParametricNullness 1431 U apply(DeferredCloser closer, @ParametricNullness V1 value1, @ParametricNullness V2 value2) 1432 throws Exception; 1433 } 1434 1435 /** 1436 * A function that returns a {@link ClosingFuture} when applied to the values of the two futures 1437 * passed to {@link #whenAllSucceed(ClosingFuture, ClosingFuture)}. 1438 * 1439 * @param <V1> the type returned by the first future 1440 * @param <V2> the type returned by the second future 1441 * @param <U> the type returned by the function 1442 */ 1443 @FunctionalInterface 1444 public interface AsyncClosingFunction2< 1445 V1 extends @Nullable Object, V2 extends @Nullable Object, U extends @Nullable Object> { 1446 1447 /** 1448 * Applies this function to two inputs, or throws an exception if unable to do so. 1449 * 1450 * <p>Any objects that are passed to {@link DeferredCloser#eventuallyClose(Object, Executor) 1451 * closer.eventuallyClose()} will be closed when the {@link ClosingFuture} pipeline is done 1452 * (but not before this method completes), even if this method throws or the pipeline is 1453 * cancelled. 1454 */ 1455 ClosingFuture<U> apply( 1456 DeferredCloser closer, @ParametricNullness V1 value1, @ParametricNullness V2 value2) 1457 throws Exception; 1458 } 1459 1460 private final ClosingFuture<V1> future1; 1461 private final ClosingFuture<V2> future2; 1462 1463 private Combiner2(ClosingFuture<V1> future1, ClosingFuture<V2> future2) { 1464 super(true, ImmutableList.of(future1, future2)); 1465 this.future1 = future1; 1466 this.future2 = future2; 1467 } 1468 1469 /** 1470 * Returns a new {@code ClosingFuture} pipeline step derived from the inputs by applying a 1471 * combining function to their values. The function can use a {@link DeferredCloser} to capture 1472 * objects to be closed when the pipeline is done. 1473 * 1474 * <p>If this combiner was returned by {@link #whenAllSucceed(ClosingFuture, ClosingFuture)} and 1475 * any of the inputs fail, so will the returned step. 1476 * 1477 * <p>If the function throws a {@code CancellationException}, the pipeline will be cancelled. 1478 * 1479 * <p>If the function throws an {@code ExecutionException}, the cause of the thrown {@code 1480 * ExecutionException} will be extracted and used as the failure of the derived step. 1481 */ 1482 public <U extends @Nullable Object> ClosingFuture<U> call( 1483 final ClosingFunction2<V1, V2, U> function, Executor executor) { 1484 return call( 1485 new CombiningCallable<U>() { 1486 @Override 1487 @ParametricNullness 1488 public U call(DeferredCloser closer, Peeker peeker) throws Exception { 1489 return function.apply(closer, peeker.getDone(future1), peeker.getDone(future2)); 1490 } 1491 1492 @Override 1493 public String toString() { 1494 return function.toString(); 1495 } 1496 }, 1497 executor); 1498 } 1499 1500 /** 1501 * Returns a new {@code ClosingFuture} pipeline step derived from the inputs by applying a 1502 * {@code ClosingFuture}-returning function to their values. The function can use a {@link 1503 * DeferredCloser} to capture objects to be closed when the pipeline is done (other than those 1504 * captured by the returned {@link ClosingFuture}). 1505 * 1506 * <p>If this combiner was returned by {@link #whenAllSucceed(ClosingFuture, ClosingFuture)} and 1507 * any of the inputs fail, so will the returned step. 1508 * 1509 * <p>If the function throws a {@code CancellationException}, the pipeline will be cancelled. 1510 * 1511 * <p>If the function throws an {@code ExecutionException}, the cause of the thrown {@code 1512 * ExecutionException} will be extracted and used as the failure of the derived step. 1513 * 1514 * <p>If the function throws any other exception, it will be used as the failure of the derived 1515 * step. 1516 * 1517 * <p>If an exception is thrown after the function creates a {@code ClosingFuture}, then none of 1518 * the closeable objects in that {@code ClosingFuture} will be closed. 1519 * 1520 * <p>Usage guidelines for this method: 1521 * 1522 * <ul> 1523 * <li>Use this method only when calling an API that returns a {@link ListenableFuture} or a 1524 * {@code ClosingFuture}. If possible, prefer calling {@link #call(CombiningCallable, 1525 * Executor)} instead, with a function that returns the next value directly. 1526 * <li>Call {@link DeferredCloser#eventuallyClose(Object, Executor) closer.eventuallyClose()} 1527 * for every closeable object this step creates in order to capture it for later closing. 1528 * <li>Return a {@code ClosingFuture}. To turn a {@link ListenableFuture} into a {@code 1529 * ClosingFuture} call {@link #from(ListenableFuture)}. 1530 * </ul> 1531 * 1532 * <p>The same warnings about doing heavyweight operations within {@link 1533 * ClosingFuture#transformAsync(AsyncClosingFunction, Executor)} apply here. 1534 */ 1535 public <U extends @Nullable Object> ClosingFuture<U> callAsync( 1536 final AsyncClosingFunction2<V1, V2, U> function, Executor executor) { 1537 return callAsync( 1538 new AsyncCombiningCallable<U>() { 1539 @Override 1540 public ClosingFuture<U> call(DeferredCloser closer, Peeker peeker) throws Exception { 1541 return function.apply(closer, peeker.getDone(future1), peeker.getDone(future2)); 1542 } 1543 1544 @Override 1545 public String toString() { 1546 return function.toString(); 1547 } 1548 }, 1549 executor); 1550 } 1551 } 1552 1553 /** 1554 * A generic {@link Combiner} that lets you use a lambda or method reference to combine three 1555 * {@link ClosingFuture}s. Use {@link #whenAllSucceed(ClosingFuture, ClosingFuture, 1556 * ClosingFuture)} to start this combination. 1557 * 1558 * @param <V1> the type returned by the first future 1559 * @param <V2> the type returned by the second future 1560 * @param <V3> the type returned by the third future 1561 */ 1562 public static final class Combiner3< 1563 V1 extends @Nullable Object, V2 extends @Nullable Object, V3 extends @Nullable Object> 1564 extends Combiner { 1565 /** 1566 * A function that returns a value when applied to the values of the three futures passed to 1567 * {@link #whenAllSucceed(ClosingFuture, ClosingFuture, ClosingFuture)}. 1568 * 1569 * @param <V1> the type returned by the first future 1570 * @param <V2> the type returned by the second future 1571 * @param <V3> the type returned by the third future 1572 * @param <U> the type returned by the function 1573 */ 1574 @FunctionalInterface 1575 public interface ClosingFunction3< 1576 V1 extends @Nullable Object, 1577 V2 extends @Nullable Object, 1578 V3 extends @Nullable Object, 1579 U extends @Nullable Object> { 1580 /** 1581 * Applies this function to three inputs, or throws an exception if unable to do so. 1582 * 1583 * <p>Any objects that are passed to {@link DeferredCloser#eventuallyClose(Object, Executor) 1584 * closer.eventuallyClose()} will be closed when the {@link ClosingFuture} pipeline is done 1585 * (but not before this method completes), even if this method throws or the pipeline is 1586 * cancelled. 1587 */ 1588 @ParametricNullness 1589 U apply( 1590 DeferredCloser closer, 1591 @ParametricNullness V1 value1, 1592 @ParametricNullness V2 value2, 1593 @ParametricNullness V3 value3) 1594 throws Exception; 1595 } 1596 1597 /** 1598 * A function that returns a {@link ClosingFuture} when applied to the values of the three 1599 * futures passed to {@link #whenAllSucceed(ClosingFuture, ClosingFuture, ClosingFuture)}. 1600 * 1601 * @param <V1> the type returned by the first future 1602 * @param <V2> the type returned by the second future 1603 * @param <V3> the type returned by the third future 1604 * @param <U> the type returned by the function 1605 */ 1606 @FunctionalInterface 1607 public interface AsyncClosingFunction3< 1608 V1 extends @Nullable Object, 1609 V2 extends @Nullable Object, 1610 V3 extends @Nullable Object, 1611 U extends @Nullable Object> { 1612 /** 1613 * Applies this function to three inputs, or throws an exception if unable to do so. 1614 * 1615 * <p>Any objects that are passed to {@link DeferredCloser#eventuallyClose(Object, Executor) 1616 * closer.eventuallyClose()} will be closed when the {@link ClosingFuture} pipeline is done 1617 * (but not before this method completes), even if this method throws or the pipeline is 1618 * cancelled. 1619 */ 1620 ClosingFuture<U> apply( 1621 DeferredCloser closer, 1622 @ParametricNullness V1 value1, 1623 @ParametricNullness V2 value2, 1624 @ParametricNullness V3 value3) 1625 throws Exception; 1626 } 1627 1628 private final ClosingFuture<V1> future1; 1629 private final ClosingFuture<V2> future2; 1630 private final ClosingFuture<V3> future3; 1631 1632 private Combiner3( 1633 ClosingFuture<V1> future1, ClosingFuture<V2> future2, ClosingFuture<V3> future3) { 1634 super(true, ImmutableList.of(future1, future2, future3)); 1635 this.future1 = future1; 1636 this.future2 = future2; 1637 this.future3 = future3; 1638 } 1639 1640 /** 1641 * Returns a new {@code ClosingFuture} pipeline step derived from the inputs by applying a 1642 * combining function to their values. The function can use a {@link DeferredCloser} to capture 1643 * objects to be closed when the pipeline is done. 1644 * 1645 * <p>If this combiner was returned by {@link #whenAllSucceed(ClosingFuture, ClosingFuture, 1646 * ClosingFuture)} and any of the inputs fail, so will the returned step. 1647 * 1648 * <p>If the function throws a {@code CancellationException}, the pipeline will be cancelled. 1649 * 1650 * <p>If the function throws an {@code ExecutionException}, the cause of the thrown {@code 1651 * ExecutionException} will be extracted and used as the failure of the derived step. 1652 */ 1653 public <U extends @Nullable Object> ClosingFuture<U> call( 1654 final ClosingFunction3<V1, V2, V3, U> function, Executor executor) { 1655 return call( 1656 new CombiningCallable<U>() { 1657 @Override 1658 @ParametricNullness 1659 public U call(DeferredCloser closer, Peeker peeker) throws Exception { 1660 return function.apply( 1661 closer, 1662 peeker.getDone(future1), 1663 peeker.getDone(future2), 1664 peeker.getDone(future3)); 1665 } 1666 1667 @Override 1668 public String toString() { 1669 return function.toString(); 1670 } 1671 }, 1672 executor); 1673 } 1674 1675 /** 1676 * Returns a new {@code ClosingFuture} pipeline step derived from the inputs by applying a 1677 * {@code ClosingFuture}-returning function to their values. The function can use a {@link 1678 * DeferredCloser} to capture objects to be closed when the pipeline is done (other than those 1679 * captured by the returned {@link ClosingFuture}). 1680 * 1681 * <p>If this combiner was returned by {@link #whenAllSucceed(ClosingFuture, ClosingFuture, 1682 * ClosingFuture)} and any of the inputs fail, so will the returned step. 1683 * 1684 * <p>If the function throws a {@code CancellationException}, the pipeline will be cancelled. 1685 * 1686 * <p>If the function throws an {@code ExecutionException}, the cause of the thrown {@code 1687 * ExecutionException} will be extracted and used as the failure of the derived step. 1688 * 1689 * <p>If the function throws any other exception, it will be used as the failure of the derived 1690 * step. 1691 * 1692 * <p>If an exception is thrown after the function creates a {@code ClosingFuture}, then none of 1693 * the closeable objects in that {@code ClosingFuture} will be closed. 1694 * 1695 * <p>Usage guidelines for this method: 1696 * 1697 * <ul> 1698 * <li>Use this method only when calling an API that returns a {@link ListenableFuture} or a 1699 * {@code ClosingFuture}. If possible, prefer calling {@link #call(CombiningCallable, 1700 * Executor)} instead, with a function that returns the next value directly. 1701 * <li>Call {@link DeferredCloser#eventuallyClose(Object, Executor) closer.eventuallyClose()} 1702 * for every closeable object this step creates in order to capture it for later closing. 1703 * <li>Return a {@code ClosingFuture}. To turn a {@link ListenableFuture} into a {@code 1704 * ClosingFuture} call {@link #from(ListenableFuture)}. 1705 * </ul> 1706 * 1707 * <p>The same warnings about doing heavyweight operations within {@link 1708 * ClosingFuture#transformAsync(AsyncClosingFunction, Executor)} apply here. 1709 */ 1710 public <U extends @Nullable Object> ClosingFuture<U> callAsync( 1711 final AsyncClosingFunction3<V1, V2, V3, U> function, Executor executor) { 1712 return callAsync( 1713 new AsyncCombiningCallable<U>() { 1714 @Override 1715 public ClosingFuture<U> call(DeferredCloser closer, Peeker peeker) throws Exception { 1716 return function.apply( 1717 closer, 1718 peeker.getDone(future1), 1719 peeker.getDone(future2), 1720 peeker.getDone(future3)); 1721 } 1722 1723 @Override 1724 public String toString() { 1725 return function.toString(); 1726 } 1727 }, 1728 executor); 1729 } 1730 } 1731 1732 /** 1733 * A generic {@link Combiner} that lets you use a lambda or method reference to combine four 1734 * {@link ClosingFuture}s. Use {@link #whenAllSucceed(ClosingFuture, ClosingFuture, ClosingFuture, 1735 * ClosingFuture)} to start this combination. 1736 * 1737 * @param <V1> the type returned by the first future 1738 * @param <V2> the type returned by the second future 1739 * @param <V3> the type returned by the third future 1740 * @param <V4> the type returned by the fourth future 1741 */ 1742 public static final class Combiner4< 1743 V1 extends @Nullable Object, 1744 V2 extends @Nullable Object, 1745 V3 extends @Nullable Object, 1746 V4 extends @Nullable Object> 1747 extends Combiner { 1748 /** 1749 * A function that returns a value when applied to the values of the four futures passed to 1750 * {@link #whenAllSucceed(ClosingFuture, ClosingFuture, ClosingFuture, ClosingFuture)}. 1751 * 1752 * @param <V1> the type returned by the first future 1753 * @param <V2> the type returned by the second future 1754 * @param <V3> the type returned by the third future 1755 * @param <V4> the type returned by the fourth future 1756 * @param <U> the type returned by the function 1757 */ 1758 @FunctionalInterface 1759 public interface ClosingFunction4< 1760 V1 extends @Nullable Object, 1761 V2 extends @Nullable Object, 1762 V3 extends @Nullable Object, 1763 V4 extends @Nullable Object, 1764 U extends @Nullable Object> { 1765 /** 1766 * Applies this function to four inputs, or throws an exception if unable to do so. 1767 * 1768 * <p>Any objects that are passed to {@link DeferredCloser#eventuallyClose(Object, Executor) 1769 * closer.eventuallyClose()} will be closed when the {@link ClosingFuture} pipeline is done 1770 * (but not before this method completes), even if this method throws or the pipeline is 1771 * cancelled. 1772 */ 1773 @ParametricNullness 1774 U apply( 1775 DeferredCloser closer, 1776 @ParametricNullness V1 value1, 1777 @ParametricNullness V2 value2, 1778 @ParametricNullness V3 value3, 1779 @ParametricNullness V4 value4) 1780 throws Exception; 1781 } 1782 1783 /** 1784 * A function that returns a {@link ClosingFuture} when applied to the values of the four 1785 * futures passed to {@link #whenAllSucceed(ClosingFuture, ClosingFuture, ClosingFuture, 1786 * ClosingFuture)}. 1787 * 1788 * @param <V1> the type returned by the first future 1789 * @param <V2> the type returned by the second future 1790 * @param <V3> the type returned by the third future 1791 * @param <V4> the type returned by the fourth future 1792 * @param <U> the type returned by the function 1793 */ 1794 @FunctionalInterface 1795 public interface AsyncClosingFunction4< 1796 V1 extends @Nullable Object, 1797 V2 extends @Nullable Object, 1798 V3 extends @Nullable Object, 1799 V4 extends @Nullable Object, 1800 U extends @Nullable Object> { 1801 /** 1802 * Applies this function to four inputs, or throws an exception if unable to do so. 1803 * 1804 * <p>Any objects that are passed to {@link DeferredCloser#eventuallyClose(Object, Executor) 1805 * closer.eventuallyClose()} will be closed when the {@link ClosingFuture} pipeline is done 1806 * (but not before this method completes), even if this method throws or the pipeline is 1807 * cancelled. 1808 */ 1809 ClosingFuture<U> apply( 1810 DeferredCloser closer, 1811 @ParametricNullness V1 value1, 1812 @ParametricNullness V2 value2, 1813 @ParametricNullness V3 value3, 1814 @ParametricNullness V4 value4) 1815 throws Exception; 1816 } 1817 1818 private final ClosingFuture<V1> future1; 1819 private final ClosingFuture<V2> future2; 1820 private final ClosingFuture<V3> future3; 1821 private final ClosingFuture<V4> future4; 1822 1823 private Combiner4( 1824 ClosingFuture<V1> future1, 1825 ClosingFuture<V2> future2, 1826 ClosingFuture<V3> future3, 1827 ClosingFuture<V4> future4) { 1828 super(true, ImmutableList.of(future1, future2, future3, future4)); 1829 this.future1 = future1; 1830 this.future2 = future2; 1831 this.future3 = future3; 1832 this.future4 = future4; 1833 } 1834 1835 /** 1836 * Returns a new {@code ClosingFuture} pipeline step derived from the inputs by applying a 1837 * combining function to their values. The function can use a {@link DeferredCloser} to capture 1838 * objects to be closed when the pipeline is done. 1839 * 1840 * <p>If this combiner was returned by {@link #whenAllSucceed(ClosingFuture, ClosingFuture, 1841 * ClosingFuture, ClosingFuture)} and any of the inputs fail, so will the returned step. 1842 * 1843 * <p>If the function throws a {@code CancellationException}, the pipeline will be cancelled. 1844 * 1845 * <p>If the function throws an {@code ExecutionException}, the cause of the thrown {@code 1846 * ExecutionException} will be extracted and used as the failure of the derived step. 1847 */ 1848 public <U extends @Nullable Object> ClosingFuture<U> call( 1849 final ClosingFunction4<V1, V2, V3, V4, U> function, Executor executor) { 1850 return call( 1851 new CombiningCallable<U>() { 1852 @Override 1853 @ParametricNullness 1854 public U call(DeferredCloser closer, Peeker peeker) throws Exception { 1855 return function.apply( 1856 closer, 1857 peeker.getDone(future1), 1858 peeker.getDone(future2), 1859 peeker.getDone(future3), 1860 peeker.getDone(future4)); 1861 } 1862 1863 @Override 1864 public String toString() { 1865 return function.toString(); 1866 } 1867 }, 1868 executor); 1869 } 1870 1871 /** 1872 * Returns a new {@code ClosingFuture} pipeline step derived from the inputs by applying a 1873 * {@code ClosingFuture}-returning function to their values. The function can use a {@link 1874 * DeferredCloser} to capture objects to be closed when the pipeline is done (other than those 1875 * captured by the returned {@link ClosingFuture}). 1876 * 1877 * <p>If this combiner was returned by {@link #whenAllSucceed(ClosingFuture, ClosingFuture, 1878 * ClosingFuture, ClosingFuture)} and any of the inputs fail, so will the returned step. 1879 * 1880 * <p>If the function throws a {@code CancellationException}, the pipeline will be cancelled. 1881 * 1882 * <p>If the function throws an {@code ExecutionException}, the cause of the thrown {@code 1883 * ExecutionException} will be extracted and used as the failure of the derived step. 1884 * 1885 * <p>If the function throws any other exception, it will be used as the failure of the derived 1886 * step. 1887 * 1888 * <p>If an exception is thrown after the function creates a {@code ClosingFuture}, then none of 1889 * the closeable objects in that {@code ClosingFuture} will be closed. 1890 * 1891 * <p>Usage guidelines for this method: 1892 * 1893 * <ul> 1894 * <li>Use this method only when calling an API that returns a {@link ListenableFuture} or a 1895 * {@code ClosingFuture}. If possible, prefer calling {@link #call(CombiningCallable, 1896 * Executor)} instead, with a function that returns the next value directly. 1897 * <li>Call {@link DeferredCloser#eventuallyClose(Object, Executor) closer.eventuallyClose()} 1898 * for every closeable object this step creates in order to capture it for later closing. 1899 * <li>Return a {@code ClosingFuture}. To turn a {@link ListenableFuture} into a {@code 1900 * ClosingFuture} call {@link #from(ListenableFuture)}. 1901 * </ul> 1902 * 1903 * <p>The same warnings about doing heavyweight operations within {@link 1904 * ClosingFuture#transformAsync(AsyncClosingFunction, Executor)} apply here. 1905 */ 1906 public <U extends @Nullable Object> ClosingFuture<U> callAsync( 1907 final AsyncClosingFunction4<V1, V2, V3, V4, U> function, Executor executor) { 1908 return callAsync( 1909 new AsyncCombiningCallable<U>() { 1910 @Override 1911 public ClosingFuture<U> call(DeferredCloser closer, Peeker peeker) throws Exception { 1912 return function.apply( 1913 closer, 1914 peeker.getDone(future1), 1915 peeker.getDone(future2), 1916 peeker.getDone(future3), 1917 peeker.getDone(future4)); 1918 } 1919 1920 @Override 1921 public String toString() { 1922 return function.toString(); 1923 } 1924 }, 1925 executor); 1926 } 1927 } 1928 1929 /** 1930 * A generic {@link Combiner} that lets you use a lambda or method reference to combine five 1931 * {@link ClosingFuture}s. Use {@link #whenAllSucceed(ClosingFuture, ClosingFuture, ClosingFuture, 1932 * ClosingFuture, ClosingFuture)} to start this combination. 1933 * 1934 * @param <V1> the type returned by the first future 1935 * @param <V2> the type returned by the second future 1936 * @param <V3> the type returned by the third future 1937 * @param <V4> the type returned by the fourth future 1938 * @param <V5> the type returned by the fifth future 1939 */ 1940 public static final class Combiner5< 1941 V1 extends @Nullable Object, 1942 V2 extends @Nullable Object, 1943 V3 extends @Nullable Object, 1944 V4 extends @Nullable Object, 1945 V5 extends @Nullable Object> 1946 extends Combiner { 1947 /** 1948 * A function that returns a value when applied to the values of the five futures passed to 1949 * {@link #whenAllSucceed(ClosingFuture, ClosingFuture, ClosingFuture, ClosingFuture, 1950 * ClosingFuture)}. 1951 * 1952 * @param <V1> the type returned by the first future 1953 * @param <V2> the type returned by the second future 1954 * @param <V3> the type returned by the third future 1955 * @param <V4> the type returned by the fourth future 1956 * @param <V5> the type returned by the fifth future 1957 * @param <U> the type returned by the function 1958 */ 1959 @FunctionalInterface 1960 public interface ClosingFunction5< 1961 V1 extends @Nullable Object, 1962 V2 extends @Nullable Object, 1963 V3 extends @Nullable Object, 1964 V4 extends @Nullable Object, 1965 V5 extends @Nullable Object, 1966 U extends @Nullable Object> { 1967 /** 1968 * Applies this function to five inputs, or throws an exception if unable to do so. 1969 * 1970 * <p>Any objects that are passed to {@link DeferredCloser#eventuallyClose(Object, Executor) 1971 * closer.eventuallyClose()} will be closed when the {@link ClosingFuture} pipeline is done 1972 * (but not before this method completes), even if this method throws or the pipeline is 1973 * cancelled. 1974 */ 1975 @ParametricNullness 1976 U apply( 1977 DeferredCloser closer, 1978 @ParametricNullness V1 value1, 1979 @ParametricNullness V2 value2, 1980 @ParametricNullness V3 value3, 1981 @ParametricNullness V4 value4, 1982 @ParametricNullness V5 value5) 1983 throws Exception; 1984 } 1985 1986 /** 1987 * A function that returns a {@link ClosingFuture} when applied to the values of the five 1988 * futures passed to {@link #whenAllSucceed(ClosingFuture, ClosingFuture, ClosingFuture, 1989 * ClosingFuture, ClosingFuture)}. 1990 * 1991 * @param <V1> the type returned by the first future 1992 * @param <V2> the type returned by the second future 1993 * @param <V3> the type returned by the third future 1994 * @param <V4> the type returned by the fourth future 1995 * @param <V5> the type returned by the fifth future 1996 * @param <U> the type returned by the function 1997 */ 1998 @FunctionalInterface 1999 public interface AsyncClosingFunction5< 2000 V1 extends @Nullable Object, 2001 V2 extends @Nullable Object, 2002 V3 extends @Nullable Object, 2003 V4 extends @Nullable Object, 2004 V5 extends @Nullable Object, 2005 U extends @Nullable Object> { 2006 /** 2007 * Applies this function to five inputs, or throws an exception if unable to do so. 2008 * 2009 * <p>Any objects that are passed to {@link DeferredCloser#eventuallyClose(Object, Executor) 2010 * closer.eventuallyClose()} will be closed when the {@link ClosingFuture} pipeline is done 2011 * (but not before this method completes), even if this method throws or the pipeline is 2012 * cancelled. 2013 */ 2014 ClosingFuture<U> apply( 2015 DeferredCloser closer, 2016 @ParametricNullness V1 value1, 2017 @ParametricNullness V2 value2, 2018 @ParametricNullness V3 value3, 2019 @ParametricNullness V4 value4, 2020 @ParametricNullness V5 value5) 2021 throws Exception; 2022 } 2023 2024 private final ClosingFuture<V1> future1; 2025 private final ClosingFuture<V2> future2; 2026 private final ClosingFuture<V3> future3; 2027 private final ClosingFuture<V4> future4; 2028 private final ClosingFuture<V5> future5; 2029 2030 private Combiner5( 2031 ClosingFuture<V1> future1, 2032 ClosingFuture<V2> future2, 2033 ClosingFuture<V3> future3, 2034 ClosingFuture<V4> future4, 2035 ClosingFuture<V5> future5) { 2036 super(true, ImmutableList.of(future1, future2, future3, future4, future5)); 2037 this.future1 = future1; 2038 this.future2 = future2; 2039 this.future3 = future3; 2040 this.future4 = future4; 2041 this.future5 = future5; 2042 } 2043 2044 /** 2045 * Returns a new {@code ClosingFuture} pipeline step derived from the inputs by applying a 2046 * combining function to their values. The function can use a {@link DeferredCloser} to capture 2047 * objects to be closed when the pipeline is done. 2048 * 2049 * <p>If this combiner was returned by {@link #whenAllSucceed(ClosingFuture, ClosingFuture, 2050 * ClosingFuture, ClosingFuture, ClosingFuture)} and any of the inputs fail, so will the 2051 * returned step. 2052 * 2053 * <p>If the function throws a {@code CancellationException}, the pipeline will be cancelled. 2054 * 2055 * <p>If the function throws an {@code ExecutionException}, the cause of the thrown {@code 2056 * ExecutionException} will be extracted and used as the failure of the derived step. 2057 */ 2058 public <U extends @Nullable Object> ClosingFuture<U> call( 2059 final ClosingFunction5<V1, V2, V3, V4, V5, U> function, Executor executor) { 2060 return call( 2061 new CombiningCallable<U>() { 2062 @Override 2063 @ParametricNullness 2064 public U call(DeferredCloser closer, Peeker peeker) throws Exception { 2065 return function.apply( 2066 closer, 2067 peeker.getDone(future1), 2068 peeker.getDone(future2), 2069 peeker.getDone(future3), 2070 peeker.getDone(future4), 2071 peeker.getDone(future5)); 2072 } 2073 2074 @Override 2075 public String toString() { 2076 return function.toString(); 2077 } 2078 }, 2079 executor); 2080 } 2081 2082 /** 2083 * Returns a new {@code ClosingFuture} pipeline step derived from the inputs by applying a 2084 * {@code ClosingFuture}-returning function to their values. The function can use a {@link 2085 * DeferredCloser} to capture objects to be closed when the pipeline is done (other than those 2086 * captured by the returned {@link ClosingFuture}). 2087 * 2088 * <p>If this combiner was returned by {@link #whenAllSucceed(ClosingFuture, ClosingFuture, 2089 * ClosingFuture, ClosingFuture, ClosingFuture)} and any of the inputs fail, so will the 2090 * returned step. 2091 * 2092 * <p>If the function throws a {@code CancellationException}, the pipeline will be cancelled. 2093 * 2094 * <p>If the function throws an {@code ExecutionException}, the cause of the thrown {@code 2095 * ExecutionException} will be extracted and used as the failure of the derived step. 2096 * 2097 * <p>If the function throws any other exception, it will be used as the failure of the derived 2098 * step. 2099 * 2100 * <p>If an exception is thrown after the function creates a {@code ClosingFuture}, then none of 2101 * the closeable objects in that {@code ClosingFuture} will be closed. 2102 * 2103 * <p>Usage guidelines for this method: 2104 * 2105 * <ul> 2106 * <li>Use this method only when calling an API that returns a {@link ListenableFuture} or a 2107 * {@code ClosingFuture}. If possible, prefer calling {@link #call(CombiningCallable, 2108 * Executor)} instead, with a function that returns the next value directly. 2109 * <li>Call {@link DeferredCloser#eventuallyClose(Object, Executor) closer.eventuallyClose()} 2110 * for every closeable object this step creates in order to capture it for later closing. 2111 * <li>Return a {@code ClosingFuture}. To turn a {@link ListenableFuture} into a {@code 2112 * ClosingFuture} call {@link #from(ListenableFuture)}. 2113 * </ul> 2114 * 2115 * <p>The same warnings about doing heavyweight operations within {@link 2116 * ClosingFuture#transformAsync(AsyncClosingFunction, Executor)} apply here. 2117 */ 2118 public <U extends @Nullable Object> ClosingFuture<U> callAsync( 2119 final AsyncClosingFunction5<V1, V2, V3, V4, V5, U> function, Executor executor) { 2120 return callAsync( 2121 new AsyncCombiningCallable<U>() { 2122 @Override 2123 public ClosingFuture<U> call(DeferredCloser closer, Peeker peeker) throws Exception { 2124 return function.apply( 2125 closer, 2126 peeker.getDone(future1), 2127 peeker.getDone(future2), 2128 peeker.getDone(future3), 2129 peeker.getDone(future4), 2130 peeker.getDone(future5)); 2131 } 2132 2133 @Override 2134 public String toString() { 2135 return function.toString(); 2136 } 2137 }, 2138 executor); 2139 } 2140 } 2141 2142 @Override 2143 public String toString() { 2144 // TODO(dpb): Better toString, in the style of Futures.transform etc. 2145 return toStringHelper(this).add("state", state.get()).addValue(future).toString(); 2146 } 2147 2148 @Override 2149 protected void finalize() { 2150 if (state.get().equals(OPEN)) { 2151 logger.log(SEVERE, "Uh oh! An open ClosingFuture has leaked and will close: {0}", this); 2152 FluentFuture<V> unused = finishToFuture(); 2153 } 2154 } 2155 2156 private static void closeQuietly(@CheckForNull final AutoCloseable closeable, Executor executor) { 2157 if (closeable == null) { 2158 return; 2159 } 2160 try { 2161 executor.execute( 2162 new Runnable() { 2163 @Override 2164 public void run() { 2165 try { 2166 closeable.close(); 2167 } catch (Exception e) { 2168 restoreInterruptIfIsInterruptedException(e); 2169 logger.log(WARNING, "thrown by close()", e); 2170 } 2171 } 2172 }); 2173 } catch (RejectedExecutionException e) { 2174 if (logger.isLoggable(WARNING)) { 2175 logger.log( 2176 WARNING, String.format("while submitting close to %s; will close inline", executor), e); 2177 } 2178 closeQuietly(closeable, directExecutor()); 2179 } 2180 } 2181 2182 private void checkAndUpdateState(State oldState, State newState) { 2183 checkState( 2184 compareAndUpdateState(oldState, newState), 2185 "Expected state to be %s, but it was %s", 2186 oldState, 2187 newState); 2188 } 2189 2190 private boolean compareAndUpdateState(State oldState, State newState) { 2191 return state.compareAndSet(oldState, newState); 2192 } 2193 2194 // TODO(dpb): Should we use a pair of ArrayLists instead of an IdentityHashMap? 2195 private static final class CloseableList extends IdentityHashMap<AutoCloseable, Executor> 2196 implements Closeable { 2197 private final DeferredCloser closer = new DeferredCloser(this); 2198 private volatile boolean closed; 2199 @CheckForNull private volatile CountDownLatch whenClosed; 2200 2201 <V extends @Nullable Object, U extends @Nullable Object> 2202 ListenableFuture<U> applyClosingFunction( 2203 ClosingFunction<? super V, U> transformation, @ParametricNullness V input) 2204 throws Exception { 2205 // TODO(dpb): Consider ways to defer closing without creating a separate CloseableList. 2206 CloseableList newCloseables = new CloseableList(); 2207 try { 2208 return immediateFuture(transformation.apply(newCloseables.closer, input)); 2209 } finally { 2210 add(newCloseables, directExecutor()); 2211 } 2212 } 2213 2214 <V extends @Nullable Object, U extends @Nullable Object> 2215 FluentFuture<U> applyAsyncClosingFunction( 2216 AsyncClosingFunction<V, U> transformation, @ParametricNullness V input) 2217 throws Exception { 2218 // TODO(dpb): Consider ways to defer closing without creating a separate CloseableList. 2219 CloseableList newCloseables = new CloseableList(); 2220 try { 2221 ClosingFuture<U> closingFuture = transformation.apply(newCloseables.closer, input); 2222 closingFuture.becomeSubsumedInto(newCloseables); 2223 return closingFuture.future; 2224 } finally { 2225 add(newCloseables, directExecutor()); 2226 } 2227 } 2228 2229 @Override 2230 public void close() { 2231 if (closed) { 2232 return; 2233 } 2234 synchronized (this) { 2235 if (closed) { 2236 return; 2237 } 2238 closed = true; 2239 } 2240 for (Map.Entry<AutoCloseable, Executor> entry : entrySet()) { 2241 closeQuietly(entry.getKey(), entry.getValue()); 2242 } 2243 clear(); 2244 if (whenClosed != null) { 2245 whenClosed.countDown(); 2246 } 2247 } 2248 2249 void add(@CheckForNull AutoCloseable closeable, Executor executor) { 2250 checkNotNull(executor); 2251 if (closeable == null) { 2252 return; 2253 } 2254 synchronized (this) { 2255 if (!closed) { 2256 put(closeable, executor); 2257 return; 2258 } 2259 } 2260 closeQuietly(closeable, executor); 2261 } 2262 2263 /** 2264 * Returns a latch that reaches zero when this objects' deferred closeables have been closed. 2265 */ 2266 CountDownLatch whenClosedCountDown() { 2267 if (closed) { 2268 return new CountDownLatch(0); 2269 } 2270 synchronized (this) { 2271 if (closed) { 2272 return new CountDownLatch(0); 2273 } 2274 checkState(whenClosed == null); 2275 return whenClosed = new CountDownLatch(1); 2276 } 2277 } 2278 } 2279 2280 /** 2281 * Returns an object that can be used to wait until this objects' deferred closeables have all had 2282 * {@link Runnable}s that close them submitted to each one's closing {@link Executor}. 2283 */ 2284 @VisibleForTesting 2285 CountDownLatch whenClosedCountDown() { 2286 return closeables.whenClosedCountDown(); 2287 } 2288 2289 /** The state of a {@link CloseableList}. */ 2290 enum State { 2291 /** The {@link CloseableList} has not been subsumed or closed. */ 2292 OPEN, 2293 2294 /** 2295 * The {@link CloseableList} has been subsumed into another. It may not be closed or subsumed 2296 * into any other. 2297 */ 2298 SUBSUMED, 2299 2300 /** 2301 * Some {@link ListenableFuture} has a callback attached that will close the {@link 2302 * CloseableList}, but it has not yet run. The {@link CloseableList} may not be subsumed. 2303 */ 2304 WILL_CLOSE, 2305 2306 /** 2307 * The callback that closes the {@link CloseableList} is running, but it has not completed. The 2308 * {@link CloseableList} may not be subsumed. 2309 */ 2310 CLOSING, 2311 2312 /** The {@link CloseableList} has been closed. It may not be further subsumed. */ 2313 CLOSED, 2314 2315 /** 2316 * {@link ClosingFuture#finishToValueAndCloser(ValueAndCloserConsumer, Executor)} has been 2317 * called. The step may not be further subsumed, nor may {@link #finishToFuture()} be called. 2318 */ 2319 WILL_CREATE_VALUE_AND_CLOSER, 2320 } 2321}