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.errorprone.annotations.DoNotMock;
018import java.util.concurrent.Executor;
019import java.util.concurrent.Future;
020import java.util.concurrent.RejectedExecutionException;
021import org.checkerframework.checker.nullness.qual.Nullable;
022
023/**
024 * A {@link Future} that accepts completion listeners. Each listener has an associated executor, and
025 * it is invoked using this executor once the future's computation is {@linkplain Future#isDone()
026 * complete}. If the computation has already completed when the listener is added, the listener will
027 * execute immediately.
028 *
029 * <p>See the Guava User Guide article on <a
030 * href="https://github.com/google/guava/wiki/ListenableFutureExplained">{@code
031 * ListenableFuture}</a>.
032 *
033 * <p>This class is GWT-compatible.
034 *
035 * <h3>Purpose</h3>
036 *
037 * <p>The main purpose of {@code ListenableFuture} is to help you chain together a graph of
038 * asynchronous operations. You can chain them together manually with calls to methods like {@link
039 * Futures#transform(ListenableFuture, com.google.common.base.Function, Executor)
040 * Futures.transform}, but you will often find it easier to use a framework. Frameworks automate the
041 * process, often adding features like monitoring, debugging, and cancellation. Examples of
042 * frameworks include:
043 *
044 * <ul>
045 *   <li><a href="https://dagger.dev/producers.html">Dagger Producers</a>
046 * </ul>
047 *
048 * <p>The main purpose of {@link #addListener addListener} is to support this chaining. You will
049 * rarely use it directly, in part because it does not provide direct access to the {@code Future}
050 * result. (If you want such access, you may prefer {@link Futures#addCallback
051 * Futures.addCallback}.) Still, direct {@code addListener} calls are occasionally useful:
052 *
053 * <pre>{@code
054 * final String name = ...;
055 * inFlight.add(name);
056 * ListenableFuture<Result> future = service.query(name);
057 * future.addListener(new Runnable() {
058 *   public void run() {
059 *     processedCount.incrementAndGet();
060 *     inFlight.remove(name);
061 *     lastProcessed.set(name);
062 *     logger.info("Done with {0}", name);
063 *   }
064 * }, executor);
065 * }</pre>
066 *
067 * <h3>How to get an instance</h3>
068 *
069 * <p>We encourage you to return {@code ListenableFuture} from your methods so that your users can
070 * take advantage of the {@linkplain Futures utilities built atop the class}. The way that you will
071 * create {@code ListenableFuture} instances depends on how you currently create {@code Future}
072 * instances:
073 *
074 * <ul>
075 *   <li>If you receive them from an {@code java.util.concurrent.ExecutorService}, convert that
076 *       service to a {@link ListeningExecutorService}, usually by calling {@link
077 *       MoreExecutors#listeningDecorator(java.util.concurrent.ExecutorService)
078 *       MoreExecutors.listeningDecorator}.
079 *   <li>If you manually call {@link java.util.concurrent.FutureTask#set} or a similar method,
080 *       create a {@link SettableFuture} instead. (If your needs are more complex, you may prefer
081 *       {@link AbstractFuture}.)
082 * </ul>
083 *
084 * <p><b>Test doubles</b>: If you need a {@code ListenableFuture} for your test, try a {@link
085 * SettableFuture} or one of the methods in the {@link Futures#immediateFuture Futures.immediate*}
086 * family. <b>Avoid</b> creating a mock or stub {@code Future}. Mock and stub implementations are
087 * fragile because they assume that only certain methods will be called and because they often
088 * implement subtleties of the API improperly.
089 *
090 * <p><b>Custom implementation</b>: Avoid implementing {@code ListenableFuture} from scratch. If you
091 * can't get by with the standard implementations, prefer to derive a new {@code Future} instance
092 * with the methods in {@link Futures} or, if necessary, to extend {@link AbstractFuture}.
093 *
094 * <p>Occasionally, an API will return a plain {@code Future} and it will be impossible to change
095 * the return type. For this case, we provide a more expensive workaround in {@code
096 * JdkFutureAdapters}. However, when possible, it is more efficient and reliable to create a {@code
097 * ListenableFuture} directly.
098 *
099 * @author Sven Mawson
100 * @author Nishant Thakkar
101 * @since 1.0
102 */
103/*
104 * Some of the annotations below were added after we released our separate
105 * com.google.guava:listenablefuture:1.0 artifact. (For more on that artifact, see
106 * https://github.com/google/guava/releases/tag/v27.0) This means that the copy of ListenableFuture
107 * in com.google.guava:guava differs from the "frozen" copy in the listenablefuture artifact. This
108 * could in principle cause problems for some users. Still, we expect that the benefits of the
109 * nullness annotations in particular will outweigh the costs. (And it's worth noting that we have
110 * released multiple ListenableFuture.class files that are not byte-for-byte compatible even from
111 * the beginning, thanks to using different `-source -target` values for compiling our `-jre` and
112 * `-android` "flavors.")
113 *
114 * (We could consider releasing a listenablefuture:1.0.1 someday. But we would want to look into how
115 * that affects users, especially users of the Android Gradle Plugin, since the plugin developers
116 * put in a special hack for us: https://issuetracker.google.com/issues/131431257)
117 */
118@DoNotMock("Use the methods in Futures (like immediateFuture) or SettableFuture")
119/*
120 * It would make sense to also annotate this class with @ElementTypesAreNonnullByDefault. However,
121 * it makes no difference because this class is already covered by the package-level
122 * @ParametersAreNonnullByDefault, and this class declares only parameters, not return types or
123 * fields. (Not to mention that we'll be removing all @*AreNonnullByDefault annotations after tools
124 * understand .) And it's fortunate that the annotation makes no difference, because
125 * we're seeing a breakage internally when we add that annotation :)
126 *
127 */
128public interface ListenableFuture<V extends @Nullable Object> extends Future<V> {
129  /**
130   * Registers a listener to be {@linkplain Executor#execute(Runnable) run} on the given executor.
131   * The listener will run when the {@code Future}'s computation is {@linkplain Future#isDone()
132   * complete} or, if the computation is already complete, immediately.
133   *
134   * <p>There is no guaranteed ordering of execution of listeners, but any listener added through
135   * this method is guaranteed to be called once the computation is complete.
136   *
137   * <p>Exceptions thrown by a listener will be propagated up to the executor. Any exception thrown
138   * during {@code Executor.execute} (e.g., a {@code RejectedExecutionException} or an exception
139   * thrown by {@linkplain MoreExecutors#directExecutor direct execution}) will be caught and
140   * logged.
141   *
142   * <p>Note: If your listener is lightweight -- and will not cause stack overflow by completing
143   * more futures or adding more {@code directExecutor()} listeners inline -- consider {@link
144   * MoreExecutors#directExecutor}. Otherwise, avoid it: See the warnings on the docs for {@code
145   * directExecutor}.
146   *
147   * <p>This is the most general listener interface. For common operations performed using
148   * listeners, see {@link Futures}. For a simplified but general listener interface, see {@link
149   * Futures#addCallback addCallback()}.
150   *
151   * <p>Memory consistency effects: Actions in a thread prior to adding a listener <a
152   * href="https://docs.oracle.com/javase/specs/jls/se7/html/jls-17.html#jls-17.4.5">
153   * <i>happen-before</i></a> its execution begins, perhaps in another thread.
154   *
155   * <p>Guava implementations of {@code ListenableFuture} promptly release references to listeners
156   * after executing them.
157   *
158   * @param listener the listener to run when the computation is complete
159   * @param executor the executor to run the listener in
160   * @throws RejectedExecutionException if we tried to execute the listener immediately but the
161   *     executor rejected it.
162   */
163  void addListener(Runnable listener, Executor executor);
164}