Interface ListenableFuture<V>
-
- All Superinterfaces:
java.util.concurrent.Future<V>
- All Known Subinterfaces:
CheckedFuture<V,X>
,ListenableScheduledFuture<V>
- All Known Implementing Classes:
AbstractCheckedFuture
,AbstractFuture
,ForwardingCheckedFuture
,ForwardingCheckedFuture.SimpleForwardingCheckedFuture
,ForwardingListenableFuture
,ForwardingListenableFuture.SimpleForwardingListenableFuture
,ListenableFutureTask
,SettableFuture
@GwtCompatible public interface ListenableFuture<V> 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
.Purpose
Most commonly,
ListenableFuture
is used as an input to another derivedFuture
, as inFutures.allAsList
. Many such methods are impossible to implement efficiently without listener support.It is possible to call
addListener
directly, but this is uncommon because theRunnable
interface does not provide direct access to theFuture
result. (Users who want such access 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
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 createListenableFuture
instances depends on how they currently createFuture
instances:- If they are returned from an
ExecutorService
, convert that service to aListeningExecutorService
, usually by callingMoreExecutors.listeningDecorator
. (Custom executors may find it more convenient to useListenableFutureTask
directly.) - If they are manually filled in by a call to
FutureTask.set(V)
or a similar method, create aSettableFuture
instead. (Users with more complex needs may preferAbstractFuture
.)
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: For fast, lightweight listeners that would be safe to execute in any thread, consider
MoreExecutors.directExecutor()
. Otherwise, avoid it. HeavyweightdirectExecutor
listeners can cause problems, and these problems can be difficult to reproduce because they depend on timing. For example:- The listener may be executed by the caller of
addListener
. That caller may be a UI thread or other latency-sensitive thread. This can harm UI responsiveness. - The listener may be executed by the thread that completes this
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. - The listener may delay other listeners, even listeners that are not
themselves
directExecutor
listeners.
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.
- Parameters:
listener
- the listener to run when the computation is completeexecutor
- the executor to run the listener in- Throws:
java.lang.NullPointerException
- if the executor or listener was nulljava.util.concurrent.RejectedExecutionException
- if we tried to execute the listener immediately but the executor rejected it.
- The listener may be executed by the caller of
-
-