001/*
002 * Copyright (C) 2007 The Guava Authors
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
005 * in compliance with the License. You may obtain a copy of the License at
006 *
007 * http://www.apache.org/licenses/LICENSE-2.0
008 *
009 * Unless required by applicable law or agreed to in writing, software distributed under the License
010 * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
011 * or implied. See the License for the specific language governing permissions and limitations under
012 * the License.
013 */
014
015package com.google.common.util.concurrent;
016
017import com.google.common.annotations.GwtCompatible;
018import java.util.concurrent.Executor;
019import java.util.concurrent.Future;
020import java.util.concurrent.RejectedExecutionException;
021
022/**
023 * A {@link Future} that accepts completion listeners. Each listener has an associated executor, and
024 * it is invoked using this executor once the future's computation is {@linkplain Future#isDone()
025 * complete}. If the computation has already completed when the listener is added, the listener will
026 * execute immediately.
027 *
028 * <p>See the Guava User Guide article on
029 * <a href="https://github.com/google/guava/wiki/ListenableFutureExplained">
030 * {@code ListenableFuture}</a>.
031 *
032 * <h3>Purpose</h3>
033 *
034 * <p>The main purpose of {@code ListenableFuture} is to help you chain together a graph of
035 * asynchronous operations. You can chain them together manually with calls to methods like
036 * {@link Futures#transform(ListenableFuture, com.google.common.base.Function, Executor)
037 * Futures.transform}, but you will often find it easier to use a framework. Frameworks automate the
038 * process, often adding features like monitoring, debugging, and cancellation. Examples of
039 * frameworks include:
040 *
041 * <ul>
042 * <li><a href="http://google.github.io/dagger/producers.html">Dagger Producers</a>
043 * </ul>
044 *
045 * <p>The main purpose of {@link #addListener addListener} is to support this chaining. You will
046 * rarely use it directly, in part because it does not provide direct access to the {@code Future}
047 * result. (If you want such access, you may prefer {@link Futures#addCallback
048 * Futures.addCallback}.) Still, direct {@code addListener} calls are occasionally useful:
049 *
050 * <pre>   {@code
051 *   final String name = ...;
052 *   inFlight.add(name);
053 *   ListenableFuture<Result> future = service.query(name);
054 *   future.addListener(new Runnable() {
055 *     public void run() {
056 *       processedCount.incrementAndGet();
057 *       inFlight.remove(name);
058 *       lastProcessed.set(name);
059 *       logger.info("Done with {0}", name);
060 *     }
061 *   }, executor);}</pre>
062 *
063 * <h3>How to get an instance</h3>
064 *
065 * <p>We encourage you to return {@code ListenableFuture} from your methods so that your users can
066 * take advantage of the {@linkplain Futures utilities built atop the class}. The way that you will
067 * create {@code ListenableFuture} instances depends on how you currently create {@code Future}
068 * instances:
069 * <ul>
070 * <li>If you receive them from an {@code java.util.concurrent.ExecutorService}, convert that
071 *     service to a {@link ListeningExecutorService}, usually by calling
072 *     {@link MoreExecutors#listeningDecorator(java.util.concurrent.ExecutorService)
073 *     MoreExecutors.listeningDecorator}.
074 * <li>If you manually call {@link java.util.concurrent.FutureTask#set} or a similar method, create
075 *     a {@link SettableFuture} instead. (If your needs are more complex, you may prefer
076 *     {@link AbstractFuture}.)
077 * </ul>
078 *
079 * <p><b>Test doubles</b>: If you need a {@code ListenableFuture} for your test, try a {@link
080 * SettableFuture} or one of the methods in the {@link Futures#immediateFuture Futures.immediate*}
081 * family. <b>Avoid</b> creating a mock or stub {@code Future}. Mock and stub implementations are
082 * fragile because they assume that only certain methods will be called and because they often
083 * implement subtleties of the API improperly.
084 *
085 * <p><b>Custom implementation</b>: Avoid implementing {@code ListenableFuture} from scratch. If you
086 * can't get by with the standard implementations, prefer to derive a new {@code Future} instance
087 * with the methods in {@link Futures} or, if necessary, to extend {@link AbstractFuture}.
088 *
089 * <p>Occasionally, an API will return a plain {@code Future} and it will be impossible to change
090 * the return type. For this case, we provide a more expensive workaround in {@code
091 * JdkFutureAdapters}. However, when possible, it is more efficient and reliable to create a {@code
092 * ListenableFuture} directly.
093 *
094 * @author Sven Mawson
095 * @author Nishant Thakkar
096 * @since 1.0
097 */
098@GwtCompatible
099public interface ListenableFuture<V> extends Future<V> {
100  /**
101   * Registers a listener to be {@linkplain Executor#execute(Runnable) run} on the given executor.
102   * The listener will run when the {@code Future}'s computation is {@linkplain Future#isDone()
103   * complete} or, if the computation is already complete, immediately.
104   *
105   * <p>There is no guaranteed ordering of execution of listeners, but any listener added through
106   * this method is guaranteed to be called once the computation is complete.
107   *
108   * <p>Exceptions thrown by a listener will be propagated up to the executor. Any exception thrown
109   * during {@code Executor.execute} (e.g., a {@code RejectedExecutionException} or an exception
110   * thrown by {@linkplain MoreExecutors#directExecutor direct execution}) will be caught and
111   * logged.
112   *
113   * <p>Note: For fast, lightweight listeners that would be safe to execute in any thread, consider
114   * {@link MoreExecutors#directExecutor}. Otherwise, avoid it. Heavyweight {@code directExecutor}
115   * listeners can cause problems, and these problems can be difficult to reproduce because they
116   * depend on timing. For example:
117   *
118   * <ul>
119   * <li>The listener may be executed by the caller of {@code addListener}. That caller may be a UI
120   * thread or other latency-sensitive thread. This can harm UI responsiveness.
121   * <li>The listener may be executed by the thread that completes this {@code Future}. That thread
122   * may be an internal system thread such as an RPC network thread. Blocking that thread may stall
123   * progress of the whole system. It may even cause a deadlock.
124   * <li>The listener may delay other listeners, even listeners that are not themselves {@code
125   * directExecutor} listeners.
126   * </ul>
127   *
128   * <p>This is the most general listener interface. For common operations performed using
129   * listeners, see {@link Futures}. For a simplified but general listener interface, see {@link
130   * Futures#addCallback addCallback()}.
131   *
132   * <p>Memory consistency effects: Actions in a thread prior to adding a listener <a
133   * href="https://docs.oracle.com/javase/specs/jls/se7/html/jls-17.html#jls-17.4.5">
134   * <i>happen-before</i></a> its execution begins, perhaps in another thread.
135   *
136   * @param listener the listener to run when the computation is complete
137   * @param executor the executor to run the listener in
138   * @throws RejectedExecutionException if we tried to execute the listener immediately but the
139   *     executor rejected it.
140   */
141  void addListener(Runnable listener, Executor executor);
142}