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.common.annotations.GwtCompatible; 018import java.util.concurrent.Executor; 019import java.util.concurrent.Future; 020import java.util.concurrent.RejectedExecutionException; 021 022/** 023 * A {@link Future} that accepts completion listeners. Each listener has an associated executor, and 024 * it is invoked using this executor once the future's computation is {@linkplain Future#isDone() 025 * complete}. If the computation has already completed when the listener is added, the listener will 026 * execute immediately. 027 * 028 * <p>See the Guava User Guide article on 029 * <a href="https://github.com/google/guava/wiki/ListenableFutureExplained"> 030 * {@code ListenableFuture}</a>. 031 * 032 * <h3>Purpose</h3> 033 * 034 * <p>The main purpose of {@code ListenableFuture} is to help you chain together a graph of 035 * asynchronous operations. You can chain them together manually with calls to methods like 036 * {@link Futures#transform(ListenableFuture, com.google.common.base.Function, Executor) 037 * Futures.transform}, but you will often find it easier to use a framework. Frameworks automate the 038 * process, often adding features like monitoring, debugging, and cancellation. Examples of 039 * frameworks include: 040 * 041 * <ul> 042 * <li><a href="http://google.github.io/dagger/producers.html">Dagger Producers</a> 043 * </ul> 044 * 045 * <p>The main purpose of {@link #addListener addListener} is to support this chaining. You will 046 * rarely use it directly, in part because it does not provide direct access to the {@code Future} 047 * result. (If you want such access, you may prefer {@link Futures#addCallback 048 * Futures.addCallback}.) Still, direct {@code addListener} calls are occasionally useful: 049 * 050 * <pre> {@code 051 * final String name = ...; 052 * inFlight.add(name); 053 * ListenableFuture<Result> future = service.query(name); 054 * future.addListener(new Runnable() { 055 * public void run() { 056 * processedCount.incrementAndGet(); 057 * inFlight.remove(name); 058 * lastProcessed.set(name); 059 * logger.info("Done with {0}", name); 060 * } 061 * }, executor);}</pre> 062 * 063 * <h3>How to get an instance</h3> 064 * 065 * <p>We encourage you to return {@code ListenableFuture} from your methods so that your users can 066 * take advantage of the {@linkplain Futures utilities built atop the class}. The way that you will 067 * create {@code ListenableFuture} instances depends on how you currently create {@code Future} 068 * instances: 069 * <ul> 070 * <li>If you receive them from an {@code java.util.concurrent.ExecutorService}, convert that 071 * service to a {@link ListeningExecutorService}, usually by calling 072 * {@link MoreExecutors#listeningDecorator(java.util.concurrent.ExecutorService) 073 * MoreExecutors.listeningDecorator}. 074 * <li>If you manually call {@link java.util.concurrent.FutureTask#set} or a similar method, create 075 * a {@link SettableFuture} instead. (If your needs are more complex, you may prefer 076 * {@link AbstractFuture}.) 077 * </ul> 078 * 079 * <p><b>Test doubles</b>: If you need a {@code ListenableFuture} for your test, try a {@link 080 * SettableFuture} or one of the methods in the {@link Futures#immediateFuture Futures.immediate*} 081 * family. <b>Avoid</b> creating a mock or stub {@code Future}. Mock and stub implementations are 082 * fragile because they assume that only certain methods will be called and because they often 083 * implement subtleties of the API improperly. 084 * 085 * <p><b>Custom implementation</b>: Avoid implementing {@code ListenableFuture} from scratch. If you 086 * can't get by with the standard implementations, prefer to derive a new {@code Future} instance 087 * with the methods in {@link Futures} or, if necessary, to extend {@link AbstractFuture}. 088 * 089 * <p>Occasionally, an API will return a plain {@code Future} and it will be impossible to change 090 * the return type. For this case, we provide a more expensive workaround in {@code 091 * JdkFutureAdapters}. However, when possible, it is more efficient and reliable to create a {@code 092 * ListenableFuture} directly. 093 * 094 * @author Sven Mawson 095 * @author Nishant Thakkar 096 * @since 1.0 097 */ 098@GwtCompatible 099public interface ListenableFuture<V> extends Future<V> { 100 /** 101 * Registers a listener to be {@linkplain Executor#execute(Runnable) run} on the given executor. 102 * The listener will run when the {@code Future}'s computation is {@linkplain Future#isDone() 103 * complete} or, if the computation is already complete, immediately. 104 * 105 * <p>There is no guaranteed ordering of execution of listeners, but any listener added through 106 * this method is guaranteed to be called once the computation is complete. 107 * 108 * <p>Exceptions thrown by a listener will be propagated up to the executor. Any exception thrown 109 * during {@code Executor.execute} (e.g., a {@code RejectedExecutionException} or an exception 110 * thrown by {@linkplain MoreExecutors#directExecutor direct execution}) will be caught and 111 * logged. 112 * 113 * <p>Note: For fast, lightweight listeners that would be safe to execute in any thread, consider 114 * {@link MoreExecutors#directExecutor}. Otherwise, avoid it. Heavyweight {@code directExecutor} 115 * listeners can cause problems, and these problems can be difficult to reproduce because they 116 * depend on timing. For example: 117 * 118 * <ul> 119 * <li>The listener may be executed by the caller of {@code addListener}. That caller may be a UI 120 * thread or other latency-sensitive thread. This can harm UI responsiveness. 121 * <li>The listener may be executed by the thread that completes this {@code Future}. That thread 122 * may be an internal system thread such as an RPC network thread. Blocking that thread may stall 123 * progress of the whole system. It may even cause a deadlock. 124 * <li>The listener may delay other listeners, even listeners that are not themselves {@code 125 * directExecutor} listeners. 126 * </ul> 127 * 128 * <p>This is the most general listener interface. For common operations performed using 129 * listeners, see {@link Futures}. For a simplified but general listener interface, see {@link 130 * Futures#addCallback addCallback()}. 131 * 132 * <p>Memory consistency effects: Actions in a thread prior to adding a listener <a 133 * href="https://docs.oracle.com/javase/specs/jls/se7/html/jls-17.html#jls-17.4.5"> 134 * <i>happen-before</i></a> its execution begins, perhaps in another thread. 135 * 136 * @param listener the listener to run when the computation is complete 137 * @param executor the executor to run the listener in 138 * @throws RejectedExecutionException if we tried to execute the listener immediately but the 139 * executor rejected it. 140 */ 141 void addListener(Runnable listener, Executor executor); 142}