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 }