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
.
This class is GWT-compatible.
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 like Futures.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 the Future
result. (If you want such access, you 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);
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
create ListenableFuture
instances depends on how you currently create Future
instances:
java.util.concurrent.ExecutorService
, convert that
service to a ListeningExecutorService
, usually by calling MoreExecutors.listeningDecorator
.
FutureTask.set(V)
or a similar method,
create a SettableFuture
instead. (If your needs are more complex, you may prefer
AbstractFuture
.)
Test doubles: If you need a ListenableFuture
for your test, try a SettableFuture
or one of the methods in the Futures.immediate*
family. Avoid creating a mock or stub Future
. 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 new Future
instance
with the methods in Futures
or, if necessary, to extend 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 listener,
Executor executor)
Registers a listener to be run on the given executor.
|
void addListener(Runnable listener, 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.directExecutor()
. 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.
Guava implementations of ListenableFuture
promptly release references to listeners
after executing them.
listener
- the listener to run when the computation is completeexecutor
- the executor to run the listener inRejectedExecutionException
- if we tried to execute the listener immediately but the
executor rejected it.Copyright © 2010–2019. All rights reserved.