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 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()
. For heavier
listeners, directExecutor()
carries some caveats. For
example, the listener may run on an unpredictable or undesirable thread:
Future
is done at the time addListener
is
called, addListener
will execute the listener inline.
Future
is not yet done, addListener
will
schedule the listener to be run by the thread that completes this Future
, which may be an internal system thread such as an RPC network
thread.
Also note that, regardless of which thread executes the
directExecutor()
listener, all other registered but unexecuted
listeners are prevented from running during its execution, even if those
listeners are to run in other executors.
This is the most general listener interface. For common operations
performed using listeners, see Futures
. For a simplified but general
listener interface, see addCallback()
.
listener
- the listener to run when the computation is completeexecutor
- the executor to run the listener inNullPointerException
- if the executor or listener was nullRejectedExecutionException
- if we tried to execute the listener
immediately but the executor rejected it.Copyright © 2007-2024, Oracle and/or its affiliates. All Rights Reserved. Use is subject to license terms.