com.google.common.util.concurrent
Class Futures

java.lang.Object
  com.google.common.util.concurrent.Futures

public class Futures
extends Object

Static utility methods pertaining to the Future interface.

Since:

2009.09.15 tentative

Author:

Kevin Bourrillion, Nishant Thakkar, Sven Mawson

Method Summary

static <I,O> ListenableFuture<O>	chain(ListenableFuture<I> input, Function<? super I,? extends ListenableFuture<? extends O>> function) Creates a new ListenableFuture that wraps another ListenableFuture.
static <I,O> ListenableFuture<O>	chain(ListenableFuture<I> input, Function<? super I,? extends ListenableFuture<? extends O>> function, Executor exec) Creates a new ListenableFuture that wraps another ListenableFuture.
static <I,O> Future<O>	compose(Future<I> future, Function<? super I,? extends O> function) Creates a new Future that wraps another Future.
static <I,O> ListenableFuture<O>	compose(ListenableFuture<I> future, Function<? super I,? extends O> function) Creates a new ListenableFuture that wraps another ListenableFuture.
static <I,O> ListenableFuture<O>	compose(ListenableFuture<I> future, Function<? super I,? extends O> function, Executor exec) Creates a new ListenableFuture that wraps another ListenableFuture.
static <T,E extends Exception> CheckedFuture<T,E>	immediateCheckedFuture(T value) Creates a CheckedFuture which has its value set immediately upon construction.
static <T,E extends Exception> CheckedFuture<T,E>	immediateFailedCheckedFuture(E exception) Creates a CheckedFuture which has an exception set immediately upon construction.
static <T> ListenableFuture<T>	immediateFailedFuture(Throwable throwable) Creates a ListenableFuture which has an exception set immediately upon construction.
static <T> ListenableFuture<T>	immediateFuture(T value) Creates a ListenableFuture which has its value set immediately upon construction.
static <T,E extends Exception> CheckedFuture<T,E>	makeChecked(Future<T> future, Function<Exception,E> mapper) Creates a CheckedFuture out of a normal Future and a Function that maps from Exception instances into the appropriate checked type.
static <T> ListenableFuture<T>	makeListenable(Future<T> future) Creates a ListenableFuture out of a normal Future.
static <V> UninterruptibleFuture<V>	makeUninterruptible(Future<V> future) Returns an uninterruptible view of a Future.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

makeUninterruptible

public static <V> UninterruptibleFuture<V> makeUninterruptible(Future<V> future)

Returns an uninterruptible view of a Future. If a thread is interrupted during an attempt to get() from the returned future, it continues to wait on the result until it is available or the timeout elapses, and only then re-interrupts the thread.

makeListenable

public static <T> ListenableFuture<T> makeListenable(Future<T> future)

Creates a ListenableFuture out of a normal Future. The returned future will create a thread to wait for the source future to complete before executing the listeners.

Callers who have a future that subclasses FutureTask may want to instead subclass ListenableFutureTask, which adds the ListenableFuture functionality to the standard FutureTask implementation.

makeChecked

public static <T,E extends Exception> CheckedFuture<T,E> makeChecked(Future<T> future,
                                                                     Function<Exception,E> mapper)

Creates a CheckedFuture out of a normal Future and a Function that maps from Exception instances into the appropriate checked type.

The given mapping function will be applied to an InterruptedException, a CancellationException, or an ExecutionException with the actual cause of the exception. See Future.get() for details on the exceptions thrown.

immediateFuture

public static <T> ListenableFuture<T> immediateFuture(@Nullable
                                                      T value)

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. It's useful for returning something that implements the ListenableFuture interface but already has the result.

immediateCheckedFuture

public static <T,E extends Exception> CheckedFuture<T,E> immediateCheckedFuture(@Nullable
                                                                                T value)

Creates a CheckedFuture 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. It's useful for returning something that implements the CheckedFuture interface but already has the result.

immediateFailedFuture

public static <T> ListenableFuture<T> immediateFailedFuture(Throwable throwable)

Creates a ListenableFuture which has an exception 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. It's useful for returning something that implements the ListenableFuture interface but already has a failed result. Calling get() will throw the provided Throwable (wrapped in an ExecutionException).

Throws:

Error - if the throwable was an Error.

immediateFailedCheckedFuture

public static <T,E extends Exception> CheckedFuture<T,E> immediateFailedCheckedFuture(E exception)

Creates a CheckedFuture which has an exception 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. It's useful for returning something that implements the CheckedFuture interface but already has a failed result. Calling get() will throw the provided Throwable (wrapped in an ExecutionException) and calling checkedGet() will throw the provided exception itself.

Throws:

Error - if the throwable was an Error.

chain

public static <I,O> ListenableFuture<O> chain(ListenableFuture<I> input,
                                              Function<? super I,? extends ListenableFuture<? extends O>> function)

Creates a new ListenableFuture that wraps another ListenableFuture. The result of the new future is the result of the provided function called on the result of the provided future. The resulting future doesn't interrupt when aborted.

TODO: Add a version that accepts a normal Future

The typical use for this method would be when a RPC call is dependent on the results of another RPC. One would call the first RPC (input), create a function that calls another RPC based on input's result, and then call chain on input and that function to get a ListenableFuture of the result.

Parameters:

input - The future to chain

function - A function to chain 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 chain.

chain

public static <I,O> ListenableFuture<O> chain(ListenableFuture<I> input,
                                              Function<? super I,? extends ListenableFuture<? extends O>> function,
                                              Executor exec)

Creates a new ListenableFuture that wraps another ListenableFuture. The result of the new future is the result of the provided function called on the result of the provided future. The resulting future doesn't interrupt when aborted.

This version allows an arbitrary executor to be passed in for running the chained Function. When using Executors.sameThreadExecutor(), the thread chained Function executes in will be whichever thread set the result of the input Future, which may be the network thread in the case of RPC-based Futures.

Parameters:

input - The future to chain

function - A function to chain the results of the provided future to the results of the returned future.

exec - Executor to run the function in.

Returns:

A future that holds result of the chain.

compose

public static <I,O> ListenableFuture<O> compose(ListenableFuture<I> future,
                                                Function<? super I,? extends O> function)

Creates a new ListenableFuture that wraps another ListenableFuture. The result of the new future is the result of the provided function called on the result of the provided future. The resulting future doesn't interrupt when aborted.

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

Parameters:

future - The future to compose

function - A Function to compose 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 composition.

compose

public static <I,O> ListenableFuture<O> compose(ListenableFuture<I> future,
                                                Function<? super I,? extends O> function,
                                                Executor exec)

Creates a new ListenableFuture that wraps another ListenableFuture. The result of the new future is the result of the provided function called on the result of the provided future. The resulting future doesn't interrupt when aborted.

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

This version allows an arbitrary executor to be passed in for running the chained Function. When using Executors.sameThreadExecutor(), the thread chained Function executes in will be whichever thread set the result of the input Future, which may be the network thread in the case of RPC-based Futures.

Parameters:

future - The future to compose

function - A Function to compose the results of the provided future to the results of the returned future.

exec - Executor to run the function in.

Returns:

A future that holds result of the composition.

Since:

2010.01.04 tentative

compose

public static <I,O> Future<O> compose(Future<I> future,
                                      Function<? super I,? extends O> function)

Creates a new Future that wraps another Future. The result of the new future is the result of the provided function called on the result of the provided future.

An example use of this method is to convert a Future that produces a handle to an object to a future that produces the object itself.

Each call to Future<O>.get(*) results in a call to Future<I>.get(*), but function is only applied once, so it is assumed that Future<I>.get(*) is idempotent.

When calling Future.get(long, TimeUnit) on the returned future, the timeout only applies to the future passed in to this method. Any additional time taken by applying function is not considered.

Parameters:

future - The future to compose

function - A Function to compose the results of the provided future to the results of the returned future. This will be run in the thread that calls one of the varieties of get().

Returns:

A future that computes result of the composition.