Interface ListenableFuture<V extends @Nullable java.lang.Object>
-
- All Superinterfaces:
java.util.concurrent.Future<V>
- All Known Subinterfaces:
ListenableScheduledFuture<V>
- All Known Implementing Classes:
AbstractFuture
,FluentFuture
,ForwardingListenableFuture
,ForwardingListenableFuture.SimpleForwardingListenableFuture
,ListenableFutureTask
,SettableFuture
@DoNotMock("Use the methods in Futures (like immediateFuture) or SettableFuture") public interface ListenableFuture<V extends @Nullable java.lang.Object> extends java.util.concurrent.Future<V>
AFuture
that accepts completion listeners. Each listener has an associated executor, and it is invoked using this executor once the future's computation is complete. If the computation has already completed when the listener is added, the listener will execute immediately.See the Guava User Guide article on
ListenableFuture
.This class is GWT-compatible.
Purpose
The main purpose of
ListenableFuture
is to help you chain together a graph of asynchronous operations. You can chain them together manually with calls to methods likeFutures.transform
(orFluentFuture.transform
), but you will often find it easier to use a framework. Frameworks automate the process, often adding features like monitoring, debugging, and cancellation. Examples of frameworks include:The main purpose of
addListener
is to support this chaining. You will rarely use it directly, in part because it does not provide direct access to theFuture
result. (If you want such access, you may preferFutures.addCallback
.) Still, directaddListener
calls are occasionally useful:final String name = ...; inFlight.add(name); ListenableFuture<Result> future = service.query(name); future.addListener(new Runnable() { public void run() { processedCount.incrementAndGet(); inFlight.remove(name); lastProcessed.set(name); logger.info("Done with {0}", name); } }, executor);
How to get an instance
We encourage you to return
ListenableFuture
from your methods so that your users can take advantage of the utilities built atop the class. The way that you will createListenableFuture
instances depends on how you currently createFuture
instances:- If you receive them from an
java.util.concurrent.ExecutorService
, convert that service to aListeningExecutorService
, usually by callingMoreExecutors.listeningDecorator
. - If you manually call
FutureTask.set(V)
or a similar method, create aSettableFuture
instead. (If your needs are more complex, you may preferAbstractFuture
.)
Test doubles: If you need a
ListenableFuture
for your test, try aSettableFuture
or one of the methods in theFutures.immediate*
family. Avoid creating a mock or stubFuture
. Mock and stub implementations are fragile because they assume that only certain methods will be called and because they often implement subtleties of the API improperly.Custom implementation: Avoid implementing
ListenableFuture
from scratch. If you can't get by with the standard implementations, prefer to derive a newFuture
instance with the methods inFutures
or, if necessary, to extendAbstractFuture
.Occasionally, an API will return a plain
Future
and it will be impossible to change the return type. For this case, we provide a more expensive workaround inJdkFutureAdapters
. However, when possible, it is more efficient and reliable to create aListenableFuture
directly.- Since:
- 1.0
- Author:
- Sven Mawson, Nishant Thakkar
-
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description void
addListener(java.lang.Runnable listener, java.util.concurrent.Executor executor)
Registers a listener to be run on the given executor.
-
-
-
Method Detail
-
addListener
void addListener(java.lang.Runnable listener, java.util.concurrent.Executor executor)
Registers a listener to be run on the given executor. The listener will run when theFuture
's computation is complete or, if the computation is already complete, immediately.There is no guaranteed ordering of execution of listeners, but any listener added through this method is guaranteed to be called once the computation is complete.
Exceptions thrown by a listener will be propagated up to the executor. Any exception thrown during
Executor.execute
(e.g., aRejectedExecutionException
or an exception thrown by direct execution) will be caught and logged.Note: If your listener is lightweight -- and will not cause stack overflow by completing more futures or adding more
directExecutor()
listeners inline -- considerMoreExecutors.directExecutor()
. Otherwise, avoid it: See the warnings on the docs fordirectExecutor
.This is the most general listener interface. For common operations performed using listeners, see
Futures
. For a simplified but general listener interface, seeaddCallback()
.Memory consistency effects: Actions in a thread prior to adding a listener happen-before its execution begins, perhaps in another thread.
Guava implementations of
ListenableFuture
promptly release references to listeners after executing them.- Parameters:
listener
- the listener to run when the computation is completeexecutor
- the executor to run the listener in- Throws:
java.util.concurrent.RejectedExecutionException
- if we tried to execute the listener immediately but the executor rejected it.
-
-