Module dev.mccue.guava.concurrent
Package dev.mccue.guava.concurrent

Interface ListenableFuture<V extends @Nullable Object>

All Superinterfaces:
Future<V>
All Known Subinterfaces:
ListenableScheduledFuture<V>
All Known Implementing Classes:
AbstractFuture, FluentFuture, ForwardingListenableFuture, ForwardingListenableFuture.SimpleForwardingListenableFuture, ListenableFutureTask, SettableFuture
@DoNotMock("Use the methods in Futures (like immediateFuture) or SettableFuture") public interface ListenableFuture<V extends @Nullable Object> 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 Future#isDone() 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.

This class is GWT-compatible.

Purpose

The main purpose of ListenableFuture is to help you chain together a graph of asynchronous operations. You can chain them together manually with calls to methods like Futures#transform(ListenableFuture, dev.mccue.guava.base.Function, Executor) Futures.transform (or FluentFuture#transform(dev.mccue.guava.base.Function, Executor) FluentFuture.transform), but you will often find it easier to use a framework. Frameworks automate the process, often adding features like monitoring, debugging, and cancellation. Examples of frameworks include:

The main purpose of #addListener addListener is to support this chaining. You will rarely use it directly, in part because it does not provide direct access to the Future result. (If you want such access, you may prefer Futures#addCallback 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.log(java.lang.System.Logger.Level.INFO, "Done with {0}", name);
   }
 }, executor);

How to get an instance

We encourage you to return ListenableFuture from your methods so that your users can take advantage of the Futures utilities built atop the class. The way that you will create ListenableFuture instances depends on how you currently create Future instances:

  • If you receive them from an java.util.concurrent.ExecutorService, convert that service to a ListeningExecutorService, usually by calling MoreExecutors#listeningDecorator(java.util.concurrent.ExecutorService) MoreExecutors.listeningDecorator.
  • If you manually call java.util.concurrent.FutureTask#set or a similar method, create a SettableFuture instead. (If your needs are more complex, you may prefer AbstractFuture.)

Test doubles: If you need a ListenableFuture for your test, try a SettableFuture or one of the methods in the Futures#immediateFuture Futures.immediate* family. Avoid creating a mock or stub Future. Mock and stub implementations are fragile because they assume that only certain methods will be called and because they often implement subtleties of the API improperly.

Custom implementation: Avoid implementing ListenableFuture from scratch. If you can't get by with the standard implementations, prefer to derive a new Future instance with the methods in Futures or, if necessary, to extend 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

    Modifier and Type
    Method
    Description
    void
    addListener(Runnable listener, Executor executor)
    Registers a listener to be Executor#execute(Runnable) run on the given executor.

    Methods inherited from interface java.util.concurrent.Future

    cancel, get, get, isCancelled, isDone

  • Method Details

    • addListener

      void addListener(Runnable listener, Executor executor)
      Registers a listener to be Executor#execute(Runnable) run on the given executor. The listener will run when the Future's computation is Future#isDone() 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 MoreExecutors#directExecutor direct execution) will be caught and logged.

      Note: If your listener is lightweight -- and will not cause stack overflow by completing more futures or adding more directExecutor() listeners inline -- consider MoreExecutors#directExecutor. Otherwise, avoid it: See the warnings on the docs for directExecutor.

      This is the most general listener interface. For common operations performed using listeners, see Futures. For a simplified but general listener interface, see Futures#addCallback addCallback().

      Memory consistency effects: Actions in a thread prior to adding a listener happen-before its execution begins, perhaps in another thread.

      Guava implementations of ListenableFuture promptly release references to listeners after executing them.

      Parameters:
      listener - the listener to run when the computation is complete
      executor - the executor to run the listener in
      Throws:
      RejectedExecutionException - if we tried to execute the listener immediately but the executor rejected it.