1 /* 2 * Copyright (C) 2007 The Guava Authors 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package com.google.common.util.concurrent; 18 19 import java.util.concurrent.Executor; 20 import java.util.concurrent.ExecutorService; 21 import java.util.concurrent.Future; 22 import java.util.concurrent.FutureTask; 23 import java.util.concurrent.RejectedExecutionException; 24 25 /** 26 * A {@link Future} that accepts completion listeners. Each listener has an 27 * associated executor, and it is invoked using this executor once the future's 28 * computation is {@linkplain Future#isDone() complete}. If the computation has 29 * already completed when the listener is added, the listener will execute 30 * immediately. 31 * 32 * <h3>Purpose</h3> 33 * 34 * Most commonly, {@code ListenableFuture} is used as an input to another 35 * derived {@code Future}, as in {@link Futures#allAsList(Iterable) 36 * Futures.allAsList}. Many such methods are impossible to implement efficiently 37 * without listener support. 38 * 39 * <p>It is possible to call {@link #addListener addListener} directly, but this 40 * is uncommon because the {@code Runnable} interface does not provide direct 41 * access to the {@code Future} result. (Users who want such access may prefer 42 * {@link Futures#addCallback Futures.addCallback}.) Still, direct {@code 43 * addListener} calls are occasionally useful:<pre> {@code 44 * final String name = ...; 45 * inFlight.add(name); 46 * ListenableFuture<Result> future = service.query(name); 47 * future.addListener(new Runnable() { 48 * public void run() { 49 * processedCount.incrementAndGet(); 50 * inFlight.remove(name); 51 * lastProcessed.set(name); 52 * logger.info("Done with {0}", name); 53 * } 54 * }, executor);}</pre> 55 * 56 * <h3>How to get an instance</h3> 57 * 58 * Developers are encouraged to return {@code ListenableFuture} from their 59 * methods so that users can take advantages of the utilities built atop the 60 * class. The way that they will create {@code ListenableFuture} instances 61 * depends on how they currently create {@code Future} instances: 62 * <ul> 63 * <li>If they are returned from an {@code ExecutorService}, convert that 64 * service to a {@link ListeningExecutorService}, usually by calling {@link 65 * MoreExecutors#listeningDecorator(ExecutorService) 66 * MoreExecutors.listeningDecorator}. (Custom executors may find it more 67 * convenient to use {@link ListenableFutureTask} directly.) 68 * <li>If they are manually filled in by a call to {@link FutureTask#set} or a 69 * similar method, create a {@link SettableFuture} instead. (Users with more 70 * complex needs may prefer {@link AbstractFuture}.) 71 * </ul> 72 * 73 * Occasionally, an API will return a plain {@code Future} and it will be 74 * impossible to change the return type. For this case, we provide a more 75 * expensive workaround in {@code JdkFutureAdapters}. However, when possible, it 76 * is more efficient and reliable to create a {@code ListenableFuture} directly. 77 * 78 * @author Sven Mawson 79 * @author Nishant Thakkar 80 * @since 1.0 81 */ 82 public interface ListenableFuture<V> extends Future<V> { 83 /** 84 * Registers a listener to be {@linkplain Executor#execute(Runnable) run} on 85 * the given executor. The listener will run when the {@code Future}'s 86 * computation is {@linkplain Future#isDone() complete} or, if the computation 87 * is already complete, immediately. 88 * 89 * <p>There is no guaranteed ordering of execution of listeners, but any 90 * listener added through this method is guaranteed to be called once the 91 * computation is complete. 92 * 93 * <p>Exceptions thrown by a listener will be propagated up to the executor. 94 * Any exception thrown during {@code Executor.execute} (e.g., a {@code 95 * RejectedExecutionException} or an exception thrown by {@linkplain 96 * MoreExecutors#sameThreadExecutor inline execution}) will be caught and 97 * logged. 98 * 99 * <p>Note: For fast, lightweight listeners that would be safe to execute in 100 * any thread, consider {@link MoreExecutors#sameThreadExecutor}. For heavier 101 * listeners, {@code sameThreadExecutor()} carries some caveats: First, the 102 * thread that the listener runs in depends on whether the {@code Future} is 103 * done at the time it is added and on whether it is ever canclled. In 104 * particular, listeners may run in the thread that calls {@code addListener} 105 * or the thread that calls {@code cancel}. Second, listeners may run in an 106 * internal thread of the system responsible for the input {@code Future}, 107 * such as an RPC network thread. Finally, during the execution of a {@code 108 * sameThreadExecutor()} listener, all other registered but unexecuted 109 * listeners are prevented from running, even if those listeners are to run 110 * in other executors. 111 * 112 * <p>This is the most general listener interface. 113 * For common operations performed using listeners, 114 * see {@link com.google.common.util.concurrent.Futures} 115 * 116 * @param listener the listener to run when the computation is complete 117 * @param executor the executor to run the listener in 118 * @throws NullPointerException if the executor or listener was null 119 * @throws RejectedExecutionException if we tried to execute the listener 120 * immediately but the executor rejected it. 121 */ 122 void addListener(Runnable listener, Executor executor); 123 } 124
