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 }