11d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert/* 21d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * Copyright (C) 2007 The Guava Authors 31d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * 41d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * Licensed under the Apache License, Version 2.0 (the "License"); 51d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * you may not use this file except in compliance with the License. 61d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * You may obtain a copy of the License at 71d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * 81d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * http://www.apache.org/licenses/LICENSE-2.0 91d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * 101d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * Unless required by applicable law or agreed to in writing, software 111d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * distributed under the License is distributed on an "AS IS" BASIS, 121d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 131d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * See the License for the specific language governing permissions and 141d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * limitations under the License. 151d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert */ 161d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert 171d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringertpackage com.google.common.util.concurrent; 181d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert 191d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringertimport java.util.concurrent.Executor; 201d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringertimport java.util.concurrent.ExecutorService; 211d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringertimport java.util.concurrent.Future; 221d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringertimport java.util.concurrent.FutureTask; 231d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringertimport java.util.concurrent.RejectedExecutionException; 241d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert 251d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert/** 261d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * A {@link Future} that accepts completion listeners. Each listener has an 271d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * associated executor, and it is invoked using this executor once the future's 281d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * computation is {@linkplain Future#isDone() complete}. If the computation has 291d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * already completed when the listener is added, the listener will execute 301d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * immediately. 311d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * 321d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * <h3>Purpose</h3> 331d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * 341d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * Most commonly, {@code ListenableFuture} is used as an input to another 351d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * derived {@code Future}, as in {@link Futures#allAsList(Iterable) 361d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * Futures.allAsList}. Many such methods are impossible to implement efficiently 371d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * without listener support. 381d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * 391d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * <p>It is possible to call {@link #addListener addListener} directly, but this 401d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * is uncommon because the {@code Runnable} interface does not provide direct 411d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * access to the {@code Future} result. (Users who want such access may prefer 421d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * {@link Futures#addCallback Futures.addCallback}.) Still, direct {@code 431d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * addListener} calls are occasionally useful:<pre> {@code 441d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * final String name = ...; 451d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * inFlight.add(name); 461d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * ListenableFuture<Result> future = service.query(name); 471d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * future.addListener(new Runnable() { 481d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * public void run() { 491d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * processedCount.incrementAndGet(); 501d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * inFlight.remove(name); 511d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * lastProcessed.set(name); 521d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * logger.info("Done with {0}", name); 531d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * } 541d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * }, executor);}</pre> 551d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * 561d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * <h3>How to get an instance</h3> 571d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * 581d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * Developers are encouraged to return {@code ListenableFuture} from their 591d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * methods so that users can take advantages of the utilities built atop the 601d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * class. The way that they will create {@code ListenableFuture} instances 611d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * depends on how they currently create {@code Future} instances: 621d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * <ul> 631d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * <li>If they are returned from an {@code ExecutorService}, convert that 641d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * service to a {@link ListeningExecutorService}, usually by calling {@link 651d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * MoreExecutors#listeningDecorator(ExecutorService) 661d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * MoreExecutors.listeningDecorator}. (Custom executors may find it more 671d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * convenient to use {@link ListenableFutureTask} directly.) 681d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * <li>If they are manually filled in by a call to {@link FutureTask#set} or a 691d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * similar method, create a {@link SettableFuture} instead. (Users with more 701d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * complex needs may prefer {@link AbstractFuture}.) 711d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * </ul> 721d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * 731d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * Occasionally, an API will return a plain {@code Future} and it will be 741d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * impossible to change the return type. For this case, we provide a more 751d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * expensive workaround in {@code JdkFutureAdapters}. However, when possible, it 761d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * is more efficient and reliable to create a {@code ListenableFuture} directly. 771d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * 781d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * @author Sven Mawson 791d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * @author Nishant Thakkar 801d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * @since 1.0 811d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert */ 821d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringertpublic interface ListenableFuture<V> extends Future<V> { 831d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert /** 841d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * Registers a listener to be {@linkplain Executor#execute(Runnable) run} on 851d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * the given executor. The listener will run when the {@code Future}'s 861d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * computation is {@linkplain Future#isDone() complete} or, if the computation 871d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * is already complete, immediately. 881d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * 891d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * <p>There is no guaranteed ordering of execution of listeners, but any 901d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * listener added through this method is guaranteed to be called once the 911d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * computation is complete. 921d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * 931d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * <p>Exceptions thrown by a listener will be propagated up to the executor. 941d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * Any exception thrown during {@code Executor.execute} (e.g., a {@code 951d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * RejectedExecutionException} or an exception thrown by {@linkplain 961d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * MoreExecutors#sameThreadExecutor inline execution}) will be caught and 971d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * logged. 981d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * 991d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * <p>Note: For fast, lightweight listeners that would be safe to execute in 1001d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * any thread, consider {@link MoreExecutors#sameThreadExecutor}. For heavier 1011d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * listeners, {@code sameThreadExecutor()} carries some caveats: First, the 1021d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * thread that the listener runs in depends on whether the {@code Future} is 1031d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * done at the time it is added and on whether it is ever canclled. In 1041d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * particular, listeners may run in the thread that calls {@code addListener} 1051d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * or the thread that calls {@code cancel}. Second, listeners may run in an 1061d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * internal thread of the system responsible for the input {@code Future}, 1071d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * such as an RPC network thread. Finally, during the execution of a {@code 1081d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * sameThreadExecutor()} listener, all other registered but unexecuted 1091d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * listeners are prevented from running, even if those listeners are to run 1101d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * in other executors. 1111d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * 1121d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * <p>This is the most general listener interface. 1131d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * For common operations performed using listeners, 1141d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * see {@link com.google.common.util.concurrent.Futures} 1151d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * 1161d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * @param listener the listener to run when the computation is complete 1171d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * @param executor the executor to run the listener in 1181d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * @throws NullPointerException if the executor or listener was null 1191d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * @throws RejectedExecutionException if we tried to execute the listener 1201d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * immediately but the executor rejected it. 1211d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert */ 1221d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert void addListener(Runnable listener, Executor executor); 1231d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert} 124