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
017package com.google.common.util.concurrent;
018
019import java.util.concurrent.Executor;
020import java.util.concurrent.ExecutorService;
021import java.util.concurrent.Future;
022import java.util.concurrent.FutureTask;
023import 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 * <p>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 * <p>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 * <p>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 */
086public 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 this {@code Future} is done at the time {@code addListener} is
110   * called, {@code addListener} will execute the listener inline.
111   * <li>If this {@code Future} is not yet done, {@code addListener} will
112   * schedule the listener to be run by the thread that completes this {@code
113   * Future}, which may be an internal system thread such as an RPC network
114   * thread.
115   * </ul>
116   *
117   * <p>Also note that, regardless of which thread executes the
118   * {@code sameThreadExecutor()} listener, all other registered but unexecuted
119   * listeners are prevented from running during its execution, even if those
120   * listeners are to run in other 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}