|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||
public interface ListenableFuture<V>
A 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.
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);
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.)
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.
| Method Summary | |
|---|---|
void |
addListener(Runnable listener,
Executor executor)
Registers a listener to be run on the given executor. |
| Methods inherited from interface java.util.concurrent.Future |
|---|
cancel, get, get, isCancelled, isDone |
| Method Detail |
|---|
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 inline execution) will be caught and
logged.
Note: For fast, lightweight listeners that would be safe to execute in
any thread, consider MoreExecutors.sameThreadExecutor(). For heavier
listeners, sameThreadExecutor() carries some caveats: First, the
thread that the listener runs in depends on whether the Future is
done at the time it is added and on whether it is ever canclled. In
particular, listeners may run in the thread that calls addListener
or the thread that calls cancel. Second, listeners may run in an
internal thread of the system responsible for the input Future,
such as an RPC network thread. Finally, during the execution of a sameThreadExecutor() listener, all other registered but unexecuted
listeners are prevented from running, 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
listener - the listener to run when the computation is completeexecutor - 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.
|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||