001 /*
002 * Copyright (C) 2007 The Guava Authors
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017 package com.google.common.util.concurrent;
018
019 import java.util.concurrent.Executor;
020 import java.util.concurrent.ExecutorService;
021 import java.util.concurrent.Future;
022 import java.util.concurrent.FutureTask;
023 import java.util.concurrent.RejectedExecutionException;
024
025 /**
026 * A {@link Future} that accepts completion listeners. Each listener has an
027 * associated executor, and it is invoked using this executor once the future's
028 * computation is {@linkplain Future#isDone() complete}. If the computation has
029 * already completed when the listener is added, the listener will execute
030 * immediately.
031 *
032 * <p>See the Guava User Guide article on <a href=
033 * "http://code.google.com/p/guava-libraries/wiki/ListenableFutureExplained">
034 * {@code ListenableFuture}</a>.
035 *
036 * <h3>Purpose</h3>
037 *
038 * Most commonly, {@code ListenableFuture} is used as an input to another
039 * derived {@code Future}, as in {@link Futures#allAsList(Iterable)
040 * Futures.allAsList}. Many such methods are impossible to implement efficiently
041 * without listener support.
042 *
043 * <p>It is possible to call {@link #addListener addListener} directly, but this
044 * is uncommon because the {@code Runnable} interface does not provide direct
045 * access to the {@code Future} result. (Users who want such access may prefer
046 * {@link Futures#addCallback Futures.addCallback}.) Still, direct {@code
047 * addListener} calls are occasionally useful:<pre> {@code
048 * final String name = ...;
049 * inFlight.add(name);
050 * ListenableFuture<Result> future = service.query(name);
051 * future.addListener(new Runnable() {
052 * public void run() {
053 * processedCount.incrementAndGet();
054 * inFlight.remove(name);
055 * lastProcessed.set(name);
056 * logger.info("Done with {0}", name);
057 * }
058 * }, executor);}</pre>
059 *
060 * <h3>How to get an instance</h3>
061 *
062 * Developers are encouraged to return {@code ListenableFuture} from their
063 * methods so that users can take advantages of the utilities built atop the
064 * class. The way that they will create {@code ListenableFuture} instances
065 * depends on how they currently create {@code Future} instances:
066 * <ul>
067 * <li>If they are returned from an {@code ExecutorService}, convert that
068 * service to a {@link ListeningExecutorService}, usually by calling {@link
069 * MoreExecutors#listeningDecorator(ExecutorService)
070 * MoreExecutors.listeningDecorator}. (Custom executors may find it more
071 * convenient to use {@link ListenableFutureTask} directly.)
072 * <li>If they are manually filled in by a call to {@link FutureTask#set} or a
073 * similar method, create a {@link SettableFuture} instead. (Users with more
074 * complex needs may prefer {@link AbstractFuture}.)
075 * </ul>
076 *
077 * Occasionally, an API will return a plain {@code Future} and it will be
078 * impossible to change the return type. For this case, we provide a more
079 * expensive workaround in {@code JdkFutureAdapters}. However, when possible, it
080 * is more efficient and reliable to create a {@code ListenableFuture} directly.
081 *
082 * @author Sven Mawson
083 * @author Nishant Thakkar
084 * @since 1.0
085 */
086 public interface ListenableFuture<V> extends Future<V> {
087 /**
088 * Registers a listener to be {@linkplain Executor#execute(Runnable) run} on
089 * the given executor. The listener will run when the {@code Future}'s
090 * computation is {@linkplain Future#isDone() complete} or, if the computation
091 * is already complete, immediately.
092 *
093 * <p>There is no guaranteed ordering of execution of listeners, but any
094 * listener added through this method is guaranteed to be called once the
095 * computation is complete.
096 *
097 * <p>Exceptions thrown by a listener will be propagated up to the executor.
098 * Any exception thrown during {@code Executor.execute} (e.g., a {@code
099 * RejectedExecutionException} or an exception thrown by {@linkplain
100 * MoreExecutors#sameThreadExecutor inline execution}) will be caught and
101 * logged.
102 *
103 * <p>Note: For fast, lightweight listeners that would be safe to execute in
104 * any thread, consider {@link MoreExecutors#sameThreadExecutor}. For heavier
105 * listeners, {@code sameThreadExecutor()} carries some caveats. For
106 * example, the listener may run on an unpredictable or undesirable thread:
107 *
108 * <ul>
109 * <li>If the input {@code Future} is done at the time {@code addListener} is
110 * called, {@code addListener} will execute the listener inline.
111 * <li>If the input {@code Future} is not yet done, {@code addListener} will
112 * schedule the listener to be run by the thread that completes the input
113 * {@code Future}, which may be an internal system thread such as an RPC
114 * network thread.
115 * </ul>
116 *
117 * Also note that, regardless of which thread executes the listener, all
118 * other registered but unexecuted listeners are prevented from running
119 * during its execution, even if those listeners are to run in other
120 * executors.
121 *
122 * <p>This is the most general listener interface. For common operations
123 * performed using listeners, see {@link
124 * com.google.common.util.concurrent.Futures}. For a simplified but general
125 * listener interface, see {@link
126 * com.google.common.util.concurrent.Futures#addCallback addCallback()}.
127 *
128 * @param listener the listener to run when the computation is complete
129 * @param executor the executor to run the listener in
130 * @throws NullPointerException if the executor or listener was null
131 * @throws RejectedExecutionException if we tried to execute the listener
132 * immediately but the executor rejected it.
133 */
134 void addListener(Runnable listener, Executor executor);
135 }