    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    }