@GwtCompatible public interface ListenableFuture<V> extends Future<V>
Future
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
.
Most commonly, ListenableFuture
is used as an input to another derived Future
, as in Futures.allAsList
. Many such methods are impossible to implement efficiently without listener support.
It is possible to call addListener
directly, but this is uncommon because the Runnable
interface does not provide direct access to the Future
result. (Users who want such access may prefer Futures.addCallback
.) Still, direct addListener
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);
Developers are encouraged to return ListenableFuture
from their methods so that users can take advantages of the utilities built atop the class. The way that they will create ListenableFuture
instances depends on how they currently create Future
instances:
ExecutorService
, convert that service to a ListeningExecutorService
, usually by calling MoreExecutors.listeningDecorator
. (Custom executors may find it more convenient to use ListenableFutureTask
directly.) FutureTask.set(V)
or a similar method, create a SettableFuture
instead. (Users with more complex needs may prefer AbstractFuture
.) 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 in JdkFutureAdapters
. However, when possible, it is more efficient and reliable to create a ListenableFuture
directly.
Modifier and Type | Method and Description |
---|---|
void |
addListener(Runnable
Registers a listener to be
run on the given executor.
|
void addListener(Runnablelistener, Executor executor)
Future
'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., a RejectedExecutionException
or an exception thrown by direct execution) will be caught and logged.
Note: For fast, lightweight listeners that would be safe to execute in any thread, consider MoreExecutors
. Otherwise, avoid it. Heavyweight directExecutor
listeners can cause problems, and these problems can be difficult to reproduce because they depend on timing. For example:
addListener
. That caller may be a UI thread or other latency-sensitive thread. This can harm UI responsiveness. Future
. That thread may be an internal system thread such as an RPC network thread. Blocking that thread may stall progress of the whole system. It may even cause a deadlock. directExecutor
listeners. This is the most general listener interface. For common operations performed using listeners, see Futures
. For a simplified but general listener interface, see addCallback()
.
Memory consistency effects: Actions in a thread prior to adding a listener happen-before its execution begins, perhaps in another thread.
listener
- the listener to run when the computation is complete
executor
- the executor to run the listener in
NullPointerException
- if the executor or listener was null
RejectedExecutionException
- if we tried to execute the listener immediately but the executor rejected it.