Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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.

See the Guava User Guide article on `ListenableFuture`.

### 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. For example, the listener may run on an unpredictable or undesirable thread:

  - If the input `Future` is done at the time `addListener` is called, `addListener` will execute the listener inline.
  - If the input `Future` is not yet done, `addListener` will schedule the listener to be run by the thread that completes the input `Future`, which may be an internal system thread such as an RPC network thread.
  Also note that, regardless of which thread executes the 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()`.

  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.

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2010-2012. All Rights Reserved.