public abstract class Futures extends Object
ListenableFuture
s.
Mostly copied after Guava's Futures
, because that one is still marked as beta
and is subject to change.
Constructor and Description |
---|
Futures() |
Modifier and Type | Method and Description |
---|---|
static <V> void |
addCallback(com.google.common.util.concurrent.ListenableFuture<V> future,
com.google.common.util.concurrent.FutureCallback<? super V> callback)
Registers separate success and failure callbacks to be run when the
Future 's computation is complete or, if the computation is already complete, immediately. |
static <V> void |
addCallback(com.google.common.util.concurrent.ListenableFuture<V> future,
com.google.common.util.concurrent.FutureCallback<? super V> callback,
Executor executor)
Registers separate success and failure callbacks to be run when the
Future 's computation is complete or, if the computation is already complete, immediately. |
static <V> com.google.common.util.concurrent.ListenableFuture<List<V>> |
allAsList(Iterable<? extends com.google.common.util.concurrent.ListenableFuture<? extends V>> futures)
Creates a new
ListenableFuture whose value is a list containing the
values of all its input futures, if all succeed. |
static <V> com.google.common.util.concurrent.ListenableFuture<List<V>> |
allAsList(com.google.common.util.concurrent.ListenableFuture<? extends V>... futures)
Creates a new
ListenableFuture whose value is a list containing the
values of all its input futures, if all succeed. |
static <V> com.google.common.util.concurrent.ListenableFuture<V> |
immediateFailedFuture(Throwable throwable)
Returns a
ListenableFuture which has an exception set immediately
upon construction. |
static <V> com.google.common.util.concurrent.ListenableFuture<V> |
immediateFuture(V value)
Creates a
ListenableFuture which has its value set immediately upon
construction. |
static <I,O> com.google.common.util.concurrent.ListenableFuture<O> |
transform(com.google.common.util.concurrent.ListenableFuture<I> future,
com.google.common.base.Function<? super I,? extends O> function)
Returns a new
ListenableFuture whose result is the product of
applying the given Function to the result of the given Future . |
static <I,O> com.google.common.util.concurrent.ListenableFuture<O> |
transform(com.google.common.util.concurrent.ListenableFuture<I> future,
com.google.common.base.Function<? super I,? extends O> function,
Executor executor)
Returns a new
ListenableFuture whose result is the product of
applying the given Function to the result of the given Future . |
public static <V> void addCallback(com.google.common.util.concurrent.ListenableFuture<V> future, com.google.common.util.concurrent.FutureCallback<? super V> callback)
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: This overload of addCallback
is designed for cases in
which the callack is fast and lightweight, as the method does not accept
an Executor
in which to perform the the work. For heavier
callbacks, this overload carries some caveats: First, the thread that the
callback runs in depends on whether the input Future
is done at the
time addCallback
is called and on whether the input Future
is ever cancelled. In particular, addCallback
may execute the
callback in the thread that calls addCallback
or Future.cancel
. Second, callbacks may run in an internal thread of the
system responsible for the input Future
, such as an RPC network
thread. Finally, during the execution of a sameThreadExecutor
callback, all other registered but unexecuted listeners are prevented from
running, 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
.
future
- The future attach the callback to.callback
- The callback to invoke when future
is completed.public static <V> void addCallback(com.google.common.util.concurrent.ListenableFuture<V> future, com.google.common.util.concurrent.FutureCallback<? super V> callback, Executor executor)
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, e,
new FutureCallback<QueryResult> {
public void onSuccess(QueryResult result) {
storeInCache(result);
}
public void onFailure(Throwable t) {
reportError(t);
}
});
When the callback is fast and lightweight consider the other overload
or explicit use of sameThreadExecutor
. For heavier callbacks, this choice carries some
caveats: First, the thread that the callback runs in depends on whether
the input Future
is done at the time addCallback
is called
and on whether the input Future
is ever cancelled. In particular,
addCallback
may execute the callback in the thread that calls
addCallback
or Future.cancel
. Second, callbacks may run in
an internal thread of the system responsible for the input Future
,
such as an RPC network thread. Finally, during the execution of a sameThreadExecutor
callback, all other registered but unexecuted
listeners are prevented from running, 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
.
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.public static <V> com.google.common.util.concurrent.ListenableFuture<V> immediateFuture(@Nullable V value)
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> com.google.common.util.concurrent.ListenableFuture<V> immediateFailedFuture(Throwable throwable)
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 <I,O> com.google.common.util.concurrent.ListenableFuture<O> transform(com.google.common.util.concurrent.ListenableFuture<I> future, com.google.common.base.Function<? super I,? extends O> function)
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: This overload of transform
is designed for cases in which
the transformation is fast and lightweight, as the method does not accept
an Executor
in which to perform the the work. For heavier
transformations, this overload carries some caveats: First, the thread
that the transformation runs in depends on whether the input Future
is done at the time transform
is called. In particular, if
called late, transform
will perform the transformation in the
thread that called transform
. Second, transformations may run in
an internal thread of the system responsible for the input Future
,
such as an RPC network thread. Finally, during the execution of a sameThreadExecutor
transformation, all other registered but unexecuted
listeners are prevented from running, 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.
future
- The future to transformfunction
- 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.compose
)public static <I,O> com.google.common.util.concurrent.ListenableFuture<O> transform(com.google.common.util.concurrent.ListenableFuture<I> future, com.google.common.base.Function<? super I,? extends O> function, Executor executor)
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.
Note: For cases in which the transformation is fast and lightweight,
consider the
other overload or explicit use of MoreExecutors.sameThreadExecutor()
. For heavier transformations, this
choice carries some caveats: First, the thread that the transformation
runs in depends on whether the input Future
is done at the time
transform
is called. In particular, if called late, transform
will perform the transformation in the thread that called
transform
. Second, transformations may run in an internal thread
of the system responsible for the input Future
, such as an RPC
network thread. Finally, during the execution of a sameThreadExecutor
transformation, all other registered but unexecuted
listeners are prevented from running, even if those listeners are to run
in other executors.
future
- The future to transformfunction
- A Function to transform the results of the provided future
to the results of the returned future.executor
- Executor to run the function in.compose
)@Beta public static <V> com.google.common.util.concurrent.ListenableFuture<List<V>> allAsList(com.google.common.util.concurrent.ListenableFuture<? extends V>... futures)
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.
The list of results is in the same order as the input list.
Canceling this future does not cancel any of the component futures; however, if any of the provided futures fails or is canceled, this one is, too.
futures
- futures to combine@Beta public static <V> com.google.common.util.concurrent.ListenableFuture<List<V>> allAsList(Iterable<? extends com.google.common.util.concurrent.ListenableFuture<? extends V>> futures)
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.
The list of results is in the same order as the input list.
Canceling this future does not cancel any of the component futures; however, if any of the provided futures fails or is canceled, this one is, too.
futures
- futures to combineCopyright © 2016–2018. All rights reserved.