com.google.common.util.concurrent
Interface ListenableFuture<V>

All Superinterfaces:

Future<V>

All Known Subinterfaces:

CheckedFuture<V,X>

All Known Implementing Classes:

AbstractCheckedFuture, AbstractFuture, ForwardingCheckedFuture, ForwardingCheckedFuture.SimpleForwardingCheckedFuture, ForwardingListenableFuture, ForwardingListenableFuture.SimpleForwardingListenableFuture, ListenableFutureTask, SettableFuture

public interface ListenableFuture<V>
extends Future<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.

Purpose

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);

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 create ListenableFuture instances depends on how they currently create Future instances:

• If they are returned from an ExecutorService, convert that service to a ListeningExecutorService, usually by calling MoreExecutors.listeningDecorator. (Custom executors may find it more convenient to use ListenableFutureTask directly.)
• If they are manually filled in by a call to 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.

Since:

1.0

Author:

Sven Mawson, Nishant Thakkar

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

addListener

void addListener(Runnable listener,
                 Executor executor)

Registers a listener to be run on the given executor. The listener will run when the 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

Parameters:

listener - the listener to run when the computation is complete

executor - the executor to run the listener in

Throws:

NullPointerException - if the executor or listener was null

RejectedExecutionException - if we tried to execute the listener immediately but the executor rejected it.