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: First, the
106       * thread that the listener runs in depends on whether the {@code Future} is
107       * done at the time it is added and on whether it is ever canclled. In
108       * particular, listeners may run in the thread that calls {@code addListener}
109       * or the thread that calls {@code cancel}. Second, listeners may run in an
110       * internal thread of the system responsible for the input {@code Future},
111       * such as an RPC network thread. Finally, during the execution of a {@code
112       * sameThreadExecutor()} listener, all other registered but unexecuted
113       * listeners are prevented from running, even if those listeners are to run
114       * in other executors.
115       *
116       * <p>This is the most general listener interface.
117       * For common operations performed using listeners,
118       * see {@link com.google.common.util.concurrent.Futures}
119       *
120       * @param listener the listener to run when the computation is complete
121       * @param executor the executor to run the listener in
122       * @throws NullPointerException if the executor or listener was null
123       * @throws RejectedExecutionException if we tried to execute the listener
124       *         immediately but the executor rejected it.
125       */
126      void addListener(Runnable listener, Executor executor);
127    }