Start line:  
End line:  

Snippet Preview

Snippet HTML Code

Stack Overflow Questions
   /*
    * Copyright (C) 2006 The Guava Authors
    *
    * Licensed under the Apache License, Version 2.0 (the "License");
    * you may not use this file except in compliance with the License.
    * You may obtain a copy of the License at
    *
    * http://www.apache.org/licenses/LICENSE-2.0
    *
   * Unless required by applicable law or agreed to in writing, software
   * distributed under the License is distributed on an "AS IS" BASIS,
   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   * See the License for the specific language governing permissions and
   * limitations under the License.
   */
  
  package com.google.common.util.concurrent;
  
  import static com.google.common.base.Preconditions.checkArgument;
  import static com.google.common.base.Preconditions.checkNotNull;
  import static com.google.common.base.Preconditions.checkState;
  import static com.google.common.util.concurrent.MoreExecutors.directExecutor;
  import static com.google.common.util.concurrent.Uninterruptibles.getUninterruptibly;
  import static java.lang.Thread.currentThread;
  import static java.util.Arrays.asList;
  
  
  import java.util.Arrays;
  import java.util.List;
  import java.util.Set;
  
Static utility methods pertaining to the java.util.concurrent.Future interface.

Many of these methods use the ListenableFuture API; consult the Guava User Guide article on ListenableFuture.

Author(s):
Kevin Bourrillion
Nishant Thakkar
Sven Mawson
Since:
1.0
  
  @Beta
  public final class Futures {
    private Futures() {}

  
Creates a CheckedFuture out of a normal ListenableFuture and a com.google.common.base.Function that maps from java.lang.Exception instances into the appropriate checked type.

The given mapping function will be applied to an java.lang.InterruptedException, a java.util.concurrent.CancellationException, or an java.util.concurrent.ExecutionException. See java.util.concurrent.Future.get() for details on the exceptions thrown.

Since:
9.0 (source-compatible since 1.0)
  
    public static <V, X extends ExceptionCheckedFuture<V, X> makeChecked(
        ListenableFuture<V> futureFunction<? super Exception, X> mapper) {
      return new MappingCheckedFuture<V, X>(checkNotNull(future), mapper);
    }
  
    private abstract static class ImmediateFuture<V>
        implements ListenableFuture<V> {
  
      private static final Logger log =
          Logger.getLogger(ImmediateFuture.class.getName());
 
     @Override
     public void addListener(Runnable listenerExecutor executor) {
       checkNotNull(listener"Runnable was null.");
       checkNotNull(executor"Executor was null.");
       try {
         executor.execute(listener);
       } catch (RuntimeException e) {
         // ListenableFuture's contract is that it will not throw unchecked
         // exceptions, so log the bad runnable and/or executor and swallow it.
         .log(."RuntimeException while executing runnable "
             + listener + " with executor " + executore);
       }
     }
 
     @Override
     public boolean cancel(boolean mayInterruptIfRunning) {
       return false;
     }
 
     @Override
     public abstract V get() throws ExecutionException;
 
     @Override
     public V get(long timeoutTimeUnit unitthrows ExecutionException {
       checkNotNull(unit);
       return get();
     }
 
     @Override
     public boolean isCancelled() {
       return false;
     }
 
     @Override
     public boolean isDone() {
       return true;
     }
   }
 
   private static class ImmediateSuccessfulFuture<V> extends ImmediateFuture<V> {
 
     @Nullable private final V value;
 
     ImmediateSuccessfulFuture(@Nullable V value) {
       this. = value;
     }
 
     @Override
     public V get() {
       return ;
     }
   }
 
   private static class ImmediateSuccessfulCheckedFuture<V, X extends Exception>
       extends ImmediateFuture<V> implements CheckedFuture<V, X> {
 
     @Nullable private final V value;
 
       this. = value;
     }
 
     @Override
     public V get() {
       return ;
     }
 
     @Override
     public V checkedGet() {
       return ;
     }
 
     @Override
     public V checkedGet(long timeoutTimeUnit unit) {
       checkNotNull(unit);
       return ;
     }
   }
 
   private static class ImmediateFailedFuture<V> extends ImmediateFuture<V> {
 
     private final Throwable thrown;
 
     ImmediateFailedFuture(Throwable thrown) {
       this. = thrown;
     }
 
     @Override
     public V get() throws ExecutionException {
       throw new ExecutionException();
     }
   }
 
   private static class ImmediateCancelledFuture<V> extends ImmediateFuture<V> {
 
     private final CancellationException thrown;
 
       this. = new CancellationException("Immediate cancelled future.");
     }
 
     @Override
     public boolean isCancelled() {
       return true;
     }
 
     @Override
     public V get() {
       throw AbstractFuture.cancellationExceptionWithCause(
           "Task was cancelled.");
     }
   }
 
   private static class ImmediateFailedCheckedFuture<V, X extends Exception>
       extends ImmediateFuture<V> implements CheckedFuture<V, X> {
 
     private final X thrown;
 
     ImmediateFailedCheckedFuture(X thrown) {
       this. = thrown;
     }
 
     @Override
     public V get() throws ExecutionException {
       throw new ExecutionException();
     }
 
     @Override
     public V checkedGet() throws X {
       throw ;
     }
 
     @Override
     public V checkedGet(long timeoutTimeUnit unitthrows X {
       checkNotNull(unit);
       throw ;
     }
   }

  
Creates a ListenableFuture which has its value set immediately upon construction. The getters just return the value. This Future can't be canceled or timed out and its isDone() method always returns true.
 
   public static <V> ListenableFuture<V> immediateFuture(@Nullable V value) {
     return new ImmediateSuccessfulFuture<V>(value);
   }

  
Returns a CheckedFuture which has its value set immediately upon construction.

The returned Future can't be cancelled, and its isDone() method always returns true. Calling get() or checkedGet() will immediately return the provided value.

 
   public static <V, X extends ExceptionCheckedFuture<V, X>
       immediateCheckedFuture(@Nullable V value) {
     return new ImmediateSuccessfulCheckedFuture<V, X>(value);
   }

  
Returns a ListenableFuture which has an exception set immediately upon construction.

The returned Future can't be cancelled, and its isDone() method always returns true. Calling get() will immediately throw the provided Throwable wrapped in an ExecutionException.

 
   public static <V> ListenableFuture<V> immediateFailedFuture(
       Throwable throwable) {
     checkNotNull(throwable);
     return new ImmediateFailedFuture<V>(throwable);
   }

  
Creates a ListenableFuture which is cancelled immediately upon construction, so that isCancelled() always returns true.

Since:
14.0
 
   public static <V> ListenableFuture<V> immediateCancelledFuture() {
     return new ImmediateCancelledFuture<V>();
   }

  
Returns a CheckedFuture which has an exception set immediately upon construction.

The returned Future can't be cancelled, and its isDone() method always returns true. Calling get() will immediately throw the provided Exception wrapped in an ExecutionException, and calling checkedGet() will throw the provided exception itself.

 
   public static <V, X extends ExceptionCheckedFuture<V, X>
       immediateFailedCheckedFuture(X exception) {
     checkNotNull(exception);
     return new ImmediateFailedCheckedFuture<V, X>(exception);
   }

  
Returns a Future whose result is taken from the given primary input or, if the primary input fails, from the Future provided by the fallback. FutureFallback.create(java.lang.Throwable) is not invoked until the primary input has failed, so if the primary input succeeds, it is never invoked. If, during the invocation of fallback, an exception is thrown, this exception is used as the result of the output Future.

Below is an example of a fallback that returns a default value if an exception occurs:

   ListenableFuture<Integer> fetchCounterFuture = ...;

   // Falling back to a zero counter in case an exception happens when
   // processing the RPC to fetch counters.
   ListenableFuture<Integer> faultTolerantFuture = Futures.withFallback(
       fetchCounterFuture, new FutureFallback<Integer>() {
         public ListenableFuture<Integer> create(Throwable t) {
           // Returning "0" as the default for the counter when the
           // exception happens.
           return immediateFuture(0);
         
       });}

The fallback can also choose to propagate the original exception when desired:

   ListenableFuture<Integer> fetchCounterFuture = ...;

   // Falling back to a zero counter only in case the exception was a
   // TimeoutException.
   ListenableFuture<Integer> faultTolerantFuture = Futures.withFallback(
       fetchCounterFuture, new FutureFallback<Integer>() {
         public ListenableFuture<Integer> create(Throwable t) {
           if (t instanceof TimeoutException) {
             return immediateFuture(0);
           
           return immediateFailedFuture(t);
         }
       });}

Note: If the derived Future is slow or heavyweight to create (whether the Future itself is slow or heavyweight to complete is irrelevant), consider supplying an executor. If you do not supply an executor, withFallback will use a direct executor, which carries some caveats for heavier operations. For example, the call to fallback.create may run on an unpredictable or undesirable thread:

  • If the input Future is done at the time withFallback is called, withFallback will call fallback.create inline.
  • If the input Future is not yet done, withFallback will schedule fallback.create to be run by the thread that completes the input Future, which may be an internal system thread such as an RPC network thread.

Also note that, regardless of which thread executes the fallback.create, all other registered but unexecuted listeners are prevented from running during its execution, even if those listeners are to run in other executors.

Parameters:
input the primary input Future
fallback the FutureFallback implementation to be called if input fails
Since:
14.0
 
   public static <V> ListenableFuture<V> withFallback(
       ListenableFuture<? extends V> input,
       FutureFallback<? extends V> fallback) {
     return withFallback(inputfallbackdirectExecutor());
   }

  
Returns a Future whose result is taken from the given primary input or, if the primary input fails, from the Future provided by the fallback. FutureFallback.create(java.lang.Throwable) is not invoked until the primary input has failed, so if the primary input succeeds, it is never invoked. If, during the invocation of fallback, an exception is thrown, this exception is used as the result of the output Future.

Below is an example of a fallback that returns a default value if an exception occurs:

   ListenableFuture<Integer> fetchCounterFuture = ...;

   // Falling back to a zero counter in case an exception happens when
   // processing the RPC to fetch counters.
   ListenableFuture<Integer> faultTolerantFuture = Futures.withFallback(
       fetchCounterFuture, new FutureFallback<Integer>() {
         public ListenableFuture<Integer> create(Throwable t) {
           // Returning "0" as the default for the counter when the
           // exception happens.
           return immediateFuture(0);
         
       }, directExecutor());}

The fallback can also choose to propagate the original exception when desired:

   ListenableFuture<Integer> fetchCounterFuture = ...;

   // Falling back to a zero counter only in case the exception was a
   // TimeoutException.
   ListenableFuture<Integer> faultTolerantFuture = Futures.withFallback(
       fetchCounterFuture, new FutureFallback<Integer>() {
         public ListenableFuture<Integer> create(Throwable t) {
           if (t instanceof TimeoutException) {
             return immediateFuture(0);
           
           return immediateFailedFuture(t);
         }
       }, directExecutor());}

When the execution of fallback.create is fast and lightweight (though the Future it returns need not meet these criteria), consider omitting the executor or explicitly specifying directExecutor. However, be aware of the caveats documented in the link above.

Parameters:
input the primary input Future
fallback the FutureFallback implementation to be called if input fails
executor the executor that runs fallback if input fails
Since:
14.0
 
   public static <V> ListenableFuture<V> withFallback(
       ListenableFuture<? extends V> input,
       FutureFallback<? extends V> fallbackExecutor executor) {
     checkNotNull(fallback);
     return new FallbackFuture<V>(inputfallbackexecutor);
   }

  
A future that falls back on a second, generated future, in case its original future fails.
 
   private static class FallbackFuture<V> extends AbstractFuture<V> {
 
     private volatile ListenableFuture<? extends V> running;
 
     FallbackFuture(ListenableFuture<? extends V> input,
         final FutureFallback<? extends V> fallback,
         final Executor executor) {
        = input;
       addCallback(new FutureCallback<V>() {
         @Override
         public void onSuccess(V value) {
           set(value);
         }
 
         @Override
         public void onFailure(Throwable t) {
           if (isCancelled()) {
             return;
           }
           try {
              = fallback.create(t);
             if (isCancelled()) { // in case cancel called in the meantime
               .cancel(wasInterrupted());
               return;
             }
             addCallback(new FutureCallback<V>() {
               @Override
               public void onSuccess(V value) {
                 set(value);
               }
 
               @Override
               public void onFailure(Throwable t) {
                 if (.isCancelled()) {
                   cancel(false);
                 } else {
                   setException(t);
                 }
               }
             }, directExecutor());
           } catch (Throwable e) {
             setException(e);
           }
         }
       }, executor);
     }
 
     @Override
     public boolean cancel(boolean mayInterruptIfRunning) {
       if (super.cancel(mayInterruptIfRunning)) {
         .cancel(mayInterruptIfRunning);
         return true;
       }
       return false;
     }
   }

  
Returns a new ListenableFuture whose result is asynchronously derived from the result of the given Future. More precisely, the returned Future takes its result from a Future produced by applying the given AsyncFunction to the result of the original Future. Example:
   ListenableFuture<RowKey> rowKeyFuture = indexService.lookUp(query);
   AsyncFunction<RowKey, QueryResult> queryFunction =
       new AsyncFunction<RowKey, QueryResult>() {
         public ListenableFuture<QueryResult> apply(RowKey rowKey) {
           return dataService.read(rowKey);
         
       };
   ListenableFuture<QueryResult> queryFuture =
       transform(rowKeyFuture, queryFunction);}

Note: If the derived Future is slow or heavyweight to create (whether the Future itself is slow or heavyweight to complete is irrelevant), consider supplying an executor. If you do not supply an executor, transform will use a direct executor, which carries some caveats for heavier operations. For example, the call to function.apply may run on an unpredictable or undesirable thread:

  • If the input Future is done at the time transform is called, transform will call function.apply inline.
  • If the input Future is not yet done, transform will schedule function.apply to be run by the thread that completes the input Future, which may be an internal system thread such as an RPC network thread.

Also note that, regardless of which thread executes the function.apply, all other registered but unexecuted listeners are prevented from running during its execution, even if those listeners are to run in other executors.

The returned Future attempts to keep its cancellation state in sync with that of the input future and that of the future returned by the function. That is, if the returned Future is cancelled, it will attempt to cancel the other two, and if either of the other two is cancelled, the returned Future will receive a callback in which it will attempt to cancel itself.

Parameters:
input The future to transform
function A function to transform the result of the input future to the result of the output future
Returns:
A future that holds result of the function (if the input succeeded) or the original input's failure (if not)
Since:
11.0
 
   public static <I, O> ListenableFuture<O> transform(ListenableFuture<I> input,
       AsyncFunction<? super I, ? extends O> function) {
     ChainingListenableFuture<I, O> output =
         new ChainingListenableFuture<I, O>(functioninput);
     input.addListener(outputdirectExecutor());
     return output;
   }

  
Returns a new ListenableFuture whose result is asynchronously derived from the result of the given Future. More precisely, the returned Future takes its result from a Future produced by applying the given AsyncFunction to the result of the original Future. Example:
   ListenableFuture<RowKey> rowKeyFuture = indexService.lookUp(query);
   AsyncFunction<RowKey, QueryResult> queryFunction =
       new AsyncFunction<RowKey, QueryResult>() {
         public ListenableFuture<QueryResult> apply(RowKey rowKey) {
           return dataService.read(rowKey);
         
       };
   ListenableFuture<QueryResult> queryFuture =
       transform(rowKeyFuture, queryFunction, executor);}

The returned Future attempts to keep its cancellation state in sync with that of the input future and that of the future returned by the chain function. That is, if the returned Future is cancelled, it will attempt to cancel the other two, and if either of the other two is cancelled, the returned Future will receive a callback in which it will attempt to cancel itself.

When the execution of function.apply is fast and lightweight (though the Future it returns need not meet these criteria), consider omitting the executor or explicitly specifying directExecutor. However, be aware of the caveats documented in the link above.

Parameters:
input The future to transform
function A function to transform the result of the input future to the result of the output future
executor Executor to run the function in.
Returns:
A future that holds result of the function (if the input succeeded) or the original input's failure (if not)
Since:
11.0
 
   public static <I, O> ListenableFuture<O> transform(ListenableFuture<I> input,
       AsyncFunction<? super I, ? extends O> function,
       Executor executor) {
     checkNotNull(executor);
     ChainingListenableFuture<I, O> output =
         new ChainingListenableFuture<I, O>(functioninput);
     input.addListener(rejectionPropagatingRunnable(outputoutputexecutor), directExecutor());
     return output;
   }

  
Returns a Runnable that will invoke the delegate Runnable on the delegate executor, but if the task is rejected, it will propagate that rejection to the output future.
 
   private static Runnable rejectionPropagatingRunnable(
       final AbstractFuture<?> outputFuture,
       final Runnable delegateTask,
       final Executor delegateExecutor) {
     return new Runnable() {
       @Override public void run() {
         final AtomicBoolean thrownFromDelegate = new AtomicBoolean(true);
         try {
           delegateExecutor.execute(new Runnable() {
             @Override public void run() {
               thrownFromDelegate.set(false);
               delegateTask.run();
             }
           });
         } catch (RejectedExecutionException e) {
           if (thrownFromDelegate.get()) {
             // wrap exception?
             outputFuture.setException(e);
           }
           // otherwise it must have been thrown from a transitive call and the delegate runnable
           // should have handled it.
         }
       }
     };
   }

  
Returns a new ListenableFuture whose result is the product of applying the given Function to the result of the given Future. Example:
   ListenableFuture<QueryResult> queryFuture = ...;
   Function<QueryResult, List<Row>> rowsFunction =
       new Function<QueryResult, List<Row>>() {
         public List<Row> apply(QueryResult queryResult) {
           return queryResult.getRows();
         
       };
   ListenableFuture<List<Row>> rowsFuture =
       transform(queryFuture, rowsFunction);}

Note: If the transformation is slow or heavyweight, consider transform(com.google.common.util.concurrent.ListenableFuture,com.google.common.base.Function,java.util.concurrent.Executor). If you do not supply an executor, transform will use an inline executor, which carries some caveats for heavier operations. For example, the call to function.apply may run on an unpredictable or undesirable thread:

  • If the input Future is done at the time transform is called, transform will call function.apply inline.
  • If the input Future is not yet done, transform will schedule function.apply to be run by the thread that completes the input Future, which may be an internal system thread such as an RPC network thread.

Also note that, regardless of which thread executes the function.apply, all other registered but unexecuted listeners are prevented from running during its execution, even if those listeners are to run in other executors.

The returned Future attempts to keep its cancellation state in sync with that of the input future. That is, if the returned Future is cancelled, it will attempt to cancel the input, and if the input is cancelled, the returned Future will receive a callback in which it will attempt to cancel itself.

An example use of this method is to convert a serializable object returned from an RPC into a POJO.

Parameters:
input The future to transform
function A Function to transform the results of the provided future to the results of the returned future. This will be run in the thread that notifies input it is complete.
Returns:
A future that holds result of the transformation.
Since:
9.0 (in 1.0 as compose)
 
   public static <I, O> ListenableFuture<O> transform(ListenableFuture<I> input,
       final Function<? super I, ? extends O> function) {
     checkNotNull(function);
     ChainingListenableFuture<I, O> output =
         new ChainingListenableFuture<I, O>(asAsyncFunction(function), input);
     input.addListener(outputdirectExecutor());
     return output;
   }

  
Returns a new ListenableFuture whose result is the product of applying the given Function to the result of the given Future. Example:
   ListenableFuture<QueryResult> queryFuture = ...;
   Function<QueryResult, List<Row>> rowsFunction =
       new Function<QueryResult, List<Row>>() {
         public List<Row> apply(QueryResult queryResult) {
           return queryResult.getRows();
         
       };
   ListenableFuture<List<Row>> rowsFuture =
       transform(queryFuture, rowsFunction, executor);}

The returned Future attempts to keep its cancellation state in sync with that of the input future. That is, if the returned Future is cancelled, it will attempt to cancel the input, and if the input is cancelled, the returned Future will receive a callback in which it will attempt to cancel itself.

An example use of this method is to convert a serializable object returned from an RPC into a POJO.

When the transformation is fast and lightweight, consider transform(com.google.common.util.concurrent.ListenableFuture,com.google.common.base.Function) or explicitly specifying directExecutor. However, be aware of the caveats documented in the link above.

Parameters:
input The future to transform
function A Function to transform the results of the provided future to the results of the returned future.
executor Executor to run the function in.
Returns:
A future that holds result of the transformation.
Since:
9.0 (in 2.0 as compose)
 
   public static <I, O> ListenableFuture<O> transform(ListenableFuture<I> input,
       final Function<? super I, ? extends O> functionExecutor executor) {
     checkNotNull(function);
     return transform(inputasAsyncFunction(function), executor);
   }

  
Wraps the given function as an AsyncFunction.
 
   private static <I, O> AsyncFunction<I, O> asAsyncFunction(
       final Function<? super I, ? extends O> function) {
     return new AsyncFunction<I, O>() {
       @Override public ListenableFuture<O> apply(I input) {
         O output = function.apply(input);
         return immediateFuture(output);
       }
     };
   }

  
Like transform(com.google.common.util.concurrent.ListenableFuture,com.google.common.base.Function) except that the transformation function is invoked on each call to get() on the returned future.

The returned Future reflects the input's cancellation state directly, and any attempt to cancel the returned Future is likewise passed through to the input Future.

Note that calls to timed get only apply the timeout to the execution of the underlying Future, not to the execution of the transformation function.

The primary audience of this method is callers of transform who don't have a ListenableFuture available and do not mind repeated, lazy function evaluation.

Parameters:
input The future to transform
function A Function to transform the results of the provided future to the results of the returned future.
Returns:
A future that returns the result of the transformation.
Since:
10.0
 
   public static <I, O> Future<O> lazyTransform(final Future<I> input,
       final Function<? super I, ? extends O> function) {
     checkNotNull(input);
     checkNotNull(function);
     return new Future<O>() {
 
       @Override
       public boolean cancel(boolean mayInterruptIfRunning) {
         return input.cancel(mayInterruptIfRunning);
       }
 
       @Override
       public boolean isCancelled() {
         return input.isCancelled();
       }
 
       @Override
       public boolean isDone() {
         return input.isDone();
       }
 
       @Override
       public O get() throws InterruptedExceptionExecutionException {
         return applyTransformation(input.get());
       }
 
       @Override
       public O get(long timeoutTimeUnit unit)
           throws InterruptedExceptionExecutionExceptionTimeoutException {
         return applyTransformation(input.get(timeoutunit));
       }
 
       private O applyTransformation(I inputthrows ExecutionException {
         try {
           return function.apply(input);
         } catch (Throwable t) {
           throw new ExecutionException(t);
         }
       }
     };
   }

  
An implementation of ListenableFuture that also implements Runnable so that it can be used to nest ListenableFutures. Once the passed-in ListenableFuture is complete, it calls the passed-in Function to generate the result.

For historical reasons, this class has a special case in its exception handling: If the given AsyncFunction throws an UndeclaredThrowableException, ChainingListenableFuture unwraps it and uses its cause as the output future's exception, rather than using the UndeclaredThrowableException itself as it would for other exception types. The reason for this is that Futures.transform used to require a Function, whose apply method is not allowed to throw checked exceptions. Nowadays, Futures.transform has an overload that accepts an AsyncFunction, whose apply method is allowed to throw checked exception. Users who wish to throw checked exceptions should use that overload instead, and we should remove the UndeclaredThrowableException special case.

 
   private static class ChainingListenableFuture<I, O>
       extends AbstractFuture<O> implements Runnable {
 
     private AsyncFunction<? super I, ? extends O> function;
     private ListenableFuture<? extends I> inputFuture;
     private volatile ListenableFuture<? extends O> outputFuture;
 
     private ChainingListenableFuture(
         AsyncFunction<? super I, ? extends O> function,
         ListenableFuture<? extends I> inputFuture) {
       this. = checkNotNull(function);
       this. = checkNotNull(inputFuture);
     }
 
     @Override
     public boolean cancel(boolean mayInterruptIfRunning) {
       /*
        * Our additional cancellation work needs to occur even if
        * !mayInterruptIfRunning, so we can't move it into interruptTask().
        */
       if (super.cancel(mayInterruptIfRunning)) {
         // This should never block since only one thread is allowed to cancel
         // this Future.
         cancel(mayInterruptIfRunning);
         cancel(mayInterruptIfRunning);
         return true;
       }
       return false;
     }
 
     private void cancel(@Nullable Future<?> future,
         boolean mayInterruptIfRunning) {
       if (future != null) {
         future.cancel(mayInterruptIfRunning);
       }
     }
 
     @Override
     public void run() {
       try {
         I sourceResult;
         try {
           sourceResult = getUninterruptibly();
         } catch (CancellationException e) {
           // Cancel this future and return.
           // At this point, inputFuture is cancelled and outputFuture doesn't
           // exist, so the value of mayInterruptIfRunning is irrelevant.
           cancel(false);
           return;
         } catch (ExecutionException e) {
           // Set the cause of the exception as this future's exception
           setException(e.getCause());
           return;
         }
 
         final ListenableFuture<? extends O> outputFuture = this. =
             Preconditions.checkNotNull(.apply(sourceResult),
                 "AsyncFunction may not return null.");
         if (isCancelled()) {
           outputFuture.cancel(wasInterrupted());
           this. = null;
           return;
         }
         outputFuture.addListener(new Runnable() {
             @Override
             public void run() {
               try {
                 set(getUninterruptibly(outputFuture));
               } catch (CancellationException e) {
                 // Cancel this future and return.
                 // At this point, inputFuture and outputFuture are done, so the
                 // value of mayInterruptIfRunning is irrelevant.
                 cancel(false);
                 return;
               } catch (ExecutionException e) {
                 // Set the cause of the exception as this future's exception
                 setException(e.getCause());
               } finally {
                 // Don't pin inputs beyond completion
                 ChainingListenableFuture.this. = null;
               }
             }
           }, directExecutor());
       } catch (UndeclaredThrowableException e) {
         // Set the cause of the exception as this future's exception
         setException(e.getCause());
       } catch (Throwable t) {
         // This exception is irrelevant in this thread, but useful for the
         // client
         setException(t);
       } finally {
         // Don't pin inputs beyond completion
          = null;
          = null;
       }
     }
   }

  
Returns a new ListenableFuture whose result is the product of calling get() on the Future nested within the given Future, effectively chaining the futures one after the other. Example:
   SettableFuture<ListenableFuture<String>> nested = SettableFuture.create();
   ListenableFuture<String> dereferenced = dereference(nested);

This call has the same cancellation and execution semantics as transform(ListenableFuture, AsyncFunction), in that the returned Future attempts to keep its cancellation state in sync with both the input Future and the nested Future. The transformation is very lightweight and therefore takes place in the same thread (either the thread that called dereference, or the thread in which the dereferenced future completes).

Parameters:
nested The nested future to transform.
Returns:
A future that holds result of the inner future.
Since:
13.0
 
   @SuppressWarnings({"rawtypes""unchecked"})
   public static <V> ListenableFuture<V> dereference(
       ListenableFuture<? extends ListenableFuture<? extends V>> nested) {
     return Futures.transform((ListenableFuturenested, (AsyncFunction);
   }

  
 
   private static final AsyncFunction<ListenableFuture<Object>, ObjectDEREFERENCER =
       new AsyncFunction<ListenableFuture<Object>, Object>() {
         @Override public ListenableFuture<Objectapply(ListenableFuture<Objectinput) {
           return input;
         }
       };

  
Creates a new ListenableFuture whose value is a list containing the values of all its input futures, if all succeed. If any input fails, the returned future fails immediately.

The list of results is in the same order as the input list.

Canceling this future will attempt to cancel all the component futures, and if any of the provided futures fails or is canceled, this one is, too.

Parameters:
futures futures to combine
Returns:
a future that provides a list of the results of the component futures
Since:
10.0
  public static <V> ListenableFuture<List<V>> allAsList(
      ListenableFuture<? extends V>... futures) {
    return listFuture(ImmutableList.copyOf(futures), truedirectExecutor());
  }

  
Creates a new ListenableFuture whose value is a list containing the values of all its input futures, if all succeed. If any input fails, the returned future fails immediately.

The list of results is in the same order as the input list.

Canceling this future will attempt to cancel all the component futures, and if any of the provided futures fails or is canceled, this one is, too.

Parameters:
futures futures to combine
Returns:
a future that provides a list of the results of the component futures
Since:
10.0
  public static <V> ListenableFuture<List<V>> allAsList(
      Iterable<? extends ListenableFuture<? extends V>> futures) {
    return listFuture(ImmutableList.copyOf(futures), truedirectExecutor());
  }
  private static final class WrappedCombiner<T> implements Callable<T> {
    final Callable<T> delegate;
    WrappedCombiner(Callable<T> delegate) {
      this. = checkNotNull(delegate);
    }
    @Override public T call() throws Exception {
      try {
        return .call();
      } catch (ExecutionException e) {
        .setException(e.getCause());
      } catch (CancellationException e) {
        .cancel(false);
      }
      // at this point the return value doesn't matter since we already called setException or
      // cancel so the future is done.
      return null;
    }
  }
  private static final class CombinerFuture<V> extends ListenableFutureTask<V> {
    CombinerFuture(Callable<V> callableImmutableList<ListenableFuture<?>> futures) {
      super(callable);
      this. = futures;
    }
    @Override public boolean cancel(boolean mayInterruptIfRunning) {
      ImmutableList<ListenableFuture<?>> futures = this.;
      if (super.cancel(mayInterruptIfRunning)) {
        for (ListenableFuture<?> future : futures) {
          future.cancel(mayInterruptIfRunning);
        }
        return true;
      }
      return false;
    }
    @Override protected void done() {
      super.done();
       = null;
    }
    @Override protected void setException(Throwable t) {
      super.setException(t);
    }
  }

  
Creates a new ListenableFuture whose result is set from the supplied future when it completes. Cancelling the supplied future will also cancel the returned future, but cancelling the returned future will have no effect on the supplied future.

Since:
15.0
  public static <V> ListenableFuture<V> nonCancellationPropagating(
      ListenableFuture<V> future) {
    return new NonCancellationPropagatingFuture<V>(future);
  }

  
A wrapped future that does not propagate cancellation to its delegate.
  private static class NonCancellationPropagatingFuture<V>
      extends AbstractFuture<V> {
      checkNotNull(delegate);
      addCallback(delegatenew FutureCallback<V>() {
        @Override
        public void onSuccess(V result) {
          set(result);
        }
        @Override
        public void onFailure(Throwable t) {
          if (delegate.isCancelled()) {
            cancel(false);
          } else {
            setException(t);
          }
        }
      }, directExecutor());
    }
  }

  
Creates a new ListenableFuture whose value is a list containing the values of all its successful input futures. The list of results is in the same order as the input list, and if any of the provided futures fails or is canceled, its corresponding position will contain null (which is indistinguishable from the future having a successful value of null).

Canceling this future will attempt to cancel all the component futures.

Parameters:
futures futures to combine
Returns:
a future that provides a list of the results of the component futures
Since:
10.0
  public static <V> ListenableFuture<List<V>> successfulAsList(
      ListenableFuture<? extends V>... futures) {
    return listFuture(ImmutableList.copyOf(futures), falsedirectExecutor());
  }

  
Creates a new ListenableFuture whose value is a list containing the values of all its successful input futures. The list of results is in the same order as the input list, and if any of the provided futures fails or is canceled, its corresponding position will contain null (which is indistinguishable from the future having a successful value of null).

Canceling this future will attempt to cancel all the component futures.

Parameters:
futures futures to combine
Returns:
a future that provides a list of the results of the component futures
Since:
10.0
  public static <V> ListenableFuture<List<V>> successfulAsList(
      Iterable<? extends ListenableFuture<? extends V>> futures) {
    return listFuture(ImmutableList.copyOf(futures), falsedirectExecutor());
  }

  
Returns a list of delegate futures that correspond to the futures received in the order that they complete. Delegate futures return the same value or throw the same exception as the corresponding input future returns/throws.

Cancelling a delegate future has no effect on any input future, since the delegate future does not correspond to a specific input future until the appropriate number of input futures have completed. At that point, it is too late to cancel the input future. The input future's result, which cannot be stored into the cancelled delegate future, is ignored.

Since:
17.0
      Iterable<? extends ListenableFuture<? extends T>> futures) {
    // A CLQ may be overkill here.  We could save some pointers/memory by synchronizing on an
    // ArrayDeque
    final ConcurrentLinkedQueue<AsyncSettableFuture<T>> delegates =
        Queues.newConcurrentLinkedQueue();
    ImmutableList.Builder<ListenableFuture<T>> listBuilder = ImmutableList.builder();
    // Using SerializingExecutor here will ensure that each CompletionOrderListener executes
    // atomically and therefore that each returned future is guaranteed to be in completion order.
    // N.B. there are some cases where the use of this executor could have possibly surprising
    // effects when input futures finish at approximately the same time _and_ the output futures
    // have directExecutor listeners. In this situation, the listeners may end up running on a
    // different thread than if they were attached to the corresponding input future.  We believe
    // this to be a negligible cost since:
    // 1. Using the directExecutor implies that your callback is safe to run on any thread.
    // 2. This would likely only be noticeable if you were doing something expensive or blocking on
    //    a directExecutor listener on one of the output futures which is an antipattern anyway.
    for (final ListenableFuture<? extends T> future : futures) {
      AsyncSettableFuture<T> delegate = AsyncSettableFuture.create();
      // Must make sure to add the delegate to the queue first in case the future is already done
      delegates.add(delegate);
      future.addListener(new Runnable() {
        @Override public void run() {
          delegates.remove().setFuture(future);
        }
      }, executor);
      listBuilder.add(delegate);
    }
    return listBuilder.build();
  }

  
Registers separate success and failure callbacks to be run when the Future's computation is complete or, if the computation is already complete, immediately.

There is no guaranteed ordering of execution of callbacks, but any callback added through this method is guaranteed to be called once the computation is complete. Example:

 ListenableFuture<QueryResult> future = ...;
 addCallback(future,
     new FutureCallback<QueryResult> {
       public void onSuccess(QueryResult result) {
         storeInCache(result);
       
       public void onFailure(Throwable t) {
         reportError(t);
       }
     });}

Note: If the callback is slow or heavyweight, consider addCallback(com.google.common.util.concurrent.ListenableFuture,com.google.common.util.concurrent.FutureCallback,java.util.concurrent.Executor). If you do not supply an executor, addCallback will use a direct executor, which carries some caveats for heavier operations. For example, the callback may run on an unpredictable or undesirable thread:

  • If the input Future is done at the time addCallback is called, addCallback will execute the callback inline.
  • If the input Future is not yet done, addCallback will schedule the callback to be run by the thread that completes the input Future, which may be an internal system thread such as an RPC network thread.

Also note that, regardless of which thread executes the callback, all other registered but unexecuted listeners are prevented from running during its execution, even if those listeners are to run in other executors.

For a more general interface to attach a completion listener to a Future, see addListener.

Parameters:
future The future attach the callback to.
callback The callback to invoke when future is completed.
Since:
10.0
  public static <V> void addCallback(ListenableFuture<V> future,
      FutureCallback<? super V> callback) {
    addCallback(futurecallbackdirectExecutor());
  }

  
Registers separate success and failure callbacks to be run when the Future's computation is complete or, if the computation is already complete, immediately.

The callback is run in executor. There is no guaranteed ordering of execution of callbacks, but any callback added through this method is guaranteed to be called once the computation is complete. Example:

 ListenableFuture<QueryResult> future = ...;
 Executor e = ...
 addCallback(future,
     new FutureCallback<QueryResult> {
       public void onSuccess(QueryResult result) {
         storeInCache(result);
       
       public void onFailure(Throwable t) {
         reportError(t);
       }
     }, e);}

When the callback is fast and lightweight, consider addCallback(com.google.common.util.concurrent.ListenableFuture,com.google.common.util.concurrent.FutureCallback) or explicitly specifying directExecutor. However, be aware of the caveats documented in the link above.

For a more general interface to attach a completion listener to a Future, see addListener.

Parameters:
future The future attach the callback to.
callback The callback to invoke when future is completed.
executor The executor to run callback when the future completes.
Since:
10.0
  public static <V> void addCallback(final ListenableFuture<V> future,
      final FutureCallback<? super V> callbackExecutor executor) {
    Preconditions.checkNotNull(callback);
    Runnable callbackListener = new Runnable() {
      @Override
      public void run() {
        final V value;
        try {
          // TODO(user): (Before Guava release), validate that this
          // is the thing for IE.
          value = getUninterruptibly(future);
        } catch (ExecutionException e) {
          callback.onFailure(e.getCause());
          return;
        } catch (RuntimeException e) {
          callback.onFailure(e);
          return;
        } catch (Error e) {
          callback.onFailure(e);
          return;
        }
        callback.onSuccess(value);
      }
    };
    future.addListener(callbackListenerexecutor);
  }

  
Returns the result of java.util.concurrent.Future.get(), converting most exceptions to a new instance of the given checked exception type. This reduces boilerplate for a common use of Future in which it is unnecessary to programmatically distinguish between exception types or to extract other information from the exception instance.

Exceptions from Future.get are treated as follows:

The overall principle is to continue to treat every checked exception as a checked exception, every unchecked exception as an unchecked exception, and every error as an error. In addition, the cause of any ExecutionException is wrapped in order to ensure that the new stack trace matches that of the current thread.

Instances of exceptionClass are created by choosing an arbitrary public constructor that accepts zero or more arguments, all of type String or Throwable (preferring constructors with at least one String) and calling the constructor via reflection. If the exception did not already have a cause, one is set by calling java.lang.Throwable.initCause(java.lang.Throwable) on it. If no such constructor exists, an IllegalArgumentException is thrown.

Throws:
X if get throws any checked exception except for an ExecutionException whose cause is not itself a checked exception
UncheckedExecutionException if get throws an ExecutionException with a RuntimeException as its cause
ExecutionError if get throws an ExecutionException with an Error as its cause
java.util.concurrent.CancellationException if get throws a CancellationException
java.lang.IllegalArgumentException if exceptionClass extends RuntimeException or does not have a suitable constructor
Since:
10.0
  public static <V, X extends Exception> V get(
      Future<V> futureClass<X> exceptionClassthrows X {
    checkNotNull(future);
    checkArgument(!RuntimeException.class.isAssignableFrom(exceptionClass),
        "Futures.get exception type (%s) must not be a RuntimeException",
        exceptionClass);
    try {
      return future.get();
    } catch (InterruptedException e) {
      currentThread().interrupt();
      throw newWithCause(exceptionClasse);
    } catch (ExecutionException e) {
      wrapAndThrowExceptionOrError(e.getCause(), exceptionClass);
      throw new AssertionError();
    }
  }

  
Returns the result of java.util.concurrent.Future.get(long,java.util.concurrent.TimeUnit), converting most exceptions to a new instance of the given checked exception type. This reduces boilerplate for a common use of Future in which it is unnecessary to programmatically distinguish between exception types or to extract other information from the exception instance.

Exceptions from Future.get are treated as follows:

The overall principle is to continue to treat every checked exception as a checked exception, every unchecked exception as an unchecked exception, and every error as an error. In addition, the cause of any ExecutionException is wrapped in order to ensure that the new stack trace matches that of the current thread.

Instances of exceptionClass are created by choosing an arbitrary public constructor that accepts zero or more arguments, all of type String or Throwable (preferring constructors with at least one String) and calling the constructor via reflection. If the exception did not already have a cause, one is set by calling java.lang.Throwable.initCause(java.lang.Throwable) on it. If no such constructor exists, an IllegalArgumentException is thrown.

Throws:
X if get throws any checked exception except for an ExecutionException whose cause is not itself a checked exception
UncheckedExecutionException if get throws an ExecutionException with a RuntimeException as its cause
ExecutionError if get throws an ExecutionException with an Error as its cause
java.util.concurrent.CancellationException if get throws a CancellationException
java.lang.IllegalArgumentException if exceptionClass extends RuntimeException or does not have a suitable constructor
Since:
10.0
  public static <V, X extends Exception> V get(
      Future<V> futurelong timeoutTimeUnit unitClass<X> exceptionClass)
      throws X {
    checkNotNull(future);
    checkNotNull(unit);
    checkArgument(!RuntimeException.class.isAssignableFrom(exceptionClass),
        "Futures.get exception type (%s) must not be a RuntimeException",
        exceptionClass);
    try {
      return future.get(timeoutunit);
    } catch (InterruptedException e) {
      currentThread().interrupt();
      throw newWithCause(exceptionClasse);
    } catch (TimeoutException e) {
      throw newWithCause(exceptionClasse);
    } catch (ExecutionException e) {
      wrapAndThrowExceptionOrError(e.getCause(), exceptionClass);
      throw new AssertionError();
    }
  }
  private static <X extends Exceptionvoid wrapAndThrowExceptionOrError(
      Throwable causeClass<X> exceptionClassthrows X {
    if (cause instanceof Error) {
      throw new ExecutionError((Errorcause);
    }
    if (cause instanceof RuntimeException) {
      throw new UncheckedExecutionException(cause);
    }
    throw newWithCause(exceptionClasscause);
  }

  
Returns the result of calling java.util.concurrent.Future.get() uninterruptibly on a task known not to throw a checked exception. This makes Future more suitable for lightweight, fast-running tasks that, barring bugs in the code, will not fail. This gives it exception-handling behavior similar to that of ForkJoinTask.join.

Exceptions from Future.get are treated as follows:

The overall principle is to eliminate all checked exceptions: to loop to avoid InterruptedException, to pass through CancellationException, and to wrap any exception from the underlying computation in an UncheckedExecutionException or ExecutionError.

For an uninterruptible get that preserves other exceptions, see Uninterruptibles.getUninterruptibly(java.util.concurrent.Future).

Throws:
UncheckedExecutionException if get throws an ExecutionException with an Exception as its cause
ExecutionError if get throws an ExecutionException with an Error as its cause
java.util.concurrent.CancellationException if get throws a CancellationException
Since:
10.0
  public static <V> V getUnchecked(Future<V> future) {
    checkNotNull(future);
    try {
      return getUninterruptibly(future);
    } catch (ExecutionException e) {
      throw new AssertionError();
    }
  }
  private static void wrapAndThrowUnchecked(Throwable cause) {
    if (cause instanceof Error) {
      throw new ExecutionError((Errorcause);
    }
    /*
     * It's a non-Error, non-Exception Throwable. From my survey of such
     * classes, I believe that most users intended to extend Exception, so we'll
     * treat it like an Exception.
     */
    throw new UncheckedExecutionException(cause);
  }
  /*
   * TODO(user): FutureChecker interface for these to be static methods on? If
   * so, refer to it in the (static-method) Futures.get documentation
   */
  /*
   * Arguably we don't need a timed getUnchecked because any operation slow
   * enough to require a timeout is heavyweight enough to throw a checked
   * exception and therefore be inappropriate to use with getUnchecked. Further,
   * it's not clear that converting the checked TimeoutException to a
   * RuntimeException -- especially to an UncheckedExecutionException, since it
   * wasn't thrown by the computation -- makes sense, and if we don't convert
   * it, the user still has to write a try-catch block.
   *
   * If you think you would use this method, let us know.
   */
  private static <X extends Exception> X newWithCause(
      Class<X> exceptionClassThrowable cause) {
    // getConstructors() guarantees this as long as we don't modify the array.
    @SuppressWarnings("unchecked")
    List<Constructor<X>> constructors =
        (List) Arrays.asList(exceptionClass.getConstructors());
    for (Constructor<X> constructor : preferringStrings(constructors)) {
      @Nullable X instance = newFromConstructor(constructorcause);
      if (instance != null) {
        if (instance.getCause() == null) {
          instance.initCause(cause);
        }
        return instance;
      }
    }
    throw new IllegalArgumentException(
        "No appropriate constructor for exception of type " + exceptionClass
            + " in response to chained exception"cause);
  }
  private static <X extends ExceptionList<Constructor<X>>
      preferringStrings(List<Constructor<X>> constructors) {
    return .sortedCopy(constructors);
  }
  private static final Ordering<Constructor<?>> WITH_STRING_PARAM_FIRST =
      Ordering.natural().onResultOf(new Function<Constructor<?>, Boolean>() {
        @Override public Boolean apply(Constructor<?> input) {
          return asList(input.getParameterTypes()).contains(String.class);
        }
      }).reverse();
  @Nullable private static <X> X newFromConstructor(
      Constructor<X> constructorThrowable cause) {
    Class<?>[] paramTypes = constructor.getParameterTypes();
    Object[] params = new Object[paramTypes.length];
    for (int i = 0; i < paramTypes.lengthi++) {
      Class<?> paramType = paramTypes[i];
      if (paramType.equals(String.class)) {
        params[i] = cause.toString();
      } else if (paramType.equals(Throwable.class)) {
        params[i] = cause;
      } else {
        return null;
      }
    }
    try {
      return constructor.newInstance(params);
    } catch (IllegalArgumentException e) {
      return null;
    } catch (InstantiationException e) {
      return null;
    } catch (IllegalAccessException e) {
      return null;
    } catch (InvocationTargetException e) {
      return null;
    }
  }
  private interface FutureCombiner<V, C> {
    C combine(List<Optional<V>> values);
  }
  private static class CombinedFuture<V, C> extends AbstractFuture<C> {
    private static final Logger logger =
        Logger.getLogger(CombinedFuture.class.getName());
    ImmutableCollection<? extends ListenableFuture<? extends V>> futures;
    final boolean allMustSucceed;
    final AtomicInteger remaining;
    FutureCombiner<V, C> combiner;
    List<Optional<V>> values;
    final Object seenExceptionsLock = new Object();
        ImmutableCollection<? extends ListenableFuture<? extends V>> futures,
        boolean allMustSucceedExecutor listenerExecutor,
        FutureCombiner<V, C> combiner) {
      this. = futures;
      this. = allMustSucceed;
      this. = new AtomicInteger(futures.size());
      this. = combiner;
      this. = Lists.newArrayListWithCapacity(futures.size());
      init(listenerExecutor);
    }

    
Must be called at the end of the constructor.
    protected void init(final Executor listenerExecutor) {
      // First, schedule cleanup to execute when the Future is done.
      addListener(new Runnable() {
        @Override
        public void run() {
          // Cancel all the component futures.
          if (CombinedFuture.this.isCancelled()) {
            for (ListenableFuture<?> future : CombinedFuture.this.) {
              future.cancel(CombinedFuture.this.wasInterrupted());
            }
          }
          // Let go of the memory held by other futures
          CombinedFuture.this. = null;
          // By now the values array has either been set as the Future's value,
          // or (in case of failure) is no longer useful.
          CombinedFuture.this. = null;
          // The combiner may also hold state, so free that as well
          CombinedFuture.this. = null;
        }
      }, directExecutor());
      // Now begin the "real" initialization.
      // Corner case: List is empty.
      if (.isEmpty()) {
        set(.combine(ImmutableList.<Optional<V>>of()));
        return;
      }
      // Populate the results list with null initially.
      for (int i = 0; i < .size(); ++i) {
        .add(null);
      }
      // Register a listener on each Future in the list to update
      // the state of this future.
      // Note that if all the futures on the list are done prior to completing
      // this loop, the last call to addListener() will callback to
      // setOneValue(), transitively call our cleanup listener, and set
      // this.futures to null.
      // This is not actually a problem, since the foreach only needs
      // this.futures to be non-null at the beginning of the loop.
      int i = 0;
      for (final ListenableFuture<? extends V> listenable : ) {
        final int index = i++;
        listenable.addListener(new Runnable() {
          @Override
          public void run() {
            setOneValue(indexlistenable);
          }
        }, listenerExecutor);
      }
    }

    
Fails this future with the given Throwable if allMustSucceed is true. Also, logs the throwable if it is an java.lang.Error or if allMustSucceed is true, the throwable did not cause this future to fail, and it is the first time we've seen that particular Throwable.
    private void setExceptionAndMaybeLog(Throwable throwable) {
      boolean visibleFromOutputFuture = false;
      boolean firstTimeSeeingThisException = true;
      if () {
        // As soon as the first one fails, throw the exception up.
        // The result of all other inputs is then ignored.
        visibleFromOutputFuture = super.setException(throwable);
        synchronized () {
          if ( == null) {
             = Sets.newHashSet();
          }
          firstTimeSeeingThisException = .add(throwable);
        }
      }
      if (throwable instanceof Error
          || ( && !visibleFromOutputFuture && firstTimeSeeingThisException)) {
        .log(."input future failed."throwable);
      }
    }

    
Sets the value at the given index to that of the given future.
    private void setOneValue(int indexFuture<? extends V> future) {
      List<Optional<V>> localValues = ;
      // TODO(user): This check appears to be redundant since values is
      // assigned null only after the future completes.  However, values
      // is not volatile so it may be possible for us to observe the changes
      // to these two values in a different order... which I think is why
      // we need to check both.  Clear up this craziness either by making
      // values volatile or proving that it doesn't need to be for some other
      // reason.
      if (isDone() || localValues == null) {
        // Some other future failed or has been cancelled, causing this one to
        // also be cancelled or have an exception set. This should only happen
        // if allMustSucceed is true or if the output itself has been
        // cancelled.
        checkState( || isCancelled(),
            "Future was done before all dependencies completed");
      }
      try {
        checkState(future.isDone(),
            "Tried to set value from future which is not done");
        V returnValue = getUninterruptibly(future);
        if (localValues != null) {
          localValues.set(index, Optional.fromNullable(returnValue));
        }