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. 317dd252788645e940eada959bdde927426e2531c9Paul Duffin * 327dd252788645e940eada959bdde927426e2531c9Paul Duffin * <p>See the Guava User Guide article on <a href= 337dd252788645e940eada959bdde927426e2531c9Paul Duffin * "http://code.google.com/p/guava-libraries/wiki/ListenableFutureExplained"> 347dd252788645e940eada959bdde927426e2531c9Paul Duffin * {@code ListenableFuture}</a>. 351d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * 361d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * <h3>Purpose</h3> 371d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * 380888a09821a98ac0680fad765217302858e70fa4Paul Duffin * <p>Most commonly, {@code ListenableFuture} is used as an input to another 391d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * derived {@code Future}, as in {@link Futures#allAsList(Iterable) 401d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * Futures.allAsList}. Many such methods are impossible to implement efficiently 411d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * without listener support. 421d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * 431d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * <p>It is possible to call {@link #addListener addListener} directly, but this 441d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * is uncommon because the {@code Runnable} interface does not provide direct 451d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * access to the {@code Future} result. (Users who want such access may prefer 461d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * {@link Futures#addCallback Futures.addCallback}.) Still, direct {@code 471d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * addListener} calls are occasionally useful:<pre> {@code 481d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * final String name = ...; 491d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * inFlight.add(name); 501d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * ListenableFuture<Result> future = service.query(name); 511d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * future.addListener(new Runnable() { 521d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * public void run() { 531d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * processedCount.incrementAndGet(); 541d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * inFlight.remove(name); 551d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * lastProcessed.set(name); 561d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * logger.info("Done with {0}", name); 571d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * } 581d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * }, executor);}</pre> 591d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * 601d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * <h3>How to get an instance</h3> 611d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * 620888a09821a98ac0680fad765217302858e70fa4Paul Duffin * <p>Developers are encouraged to return {@code ListenableFuture} from their 631d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * methods so that users can take advantages of the utilities built atop the 641d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * class. The way that they will create {@code ListenableFuture} instances 651d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * depends on how they currently create {@code Future} instances: 661d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * <ul> 671d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * <li>If they are returned from an {@code ExecutorService}, convert that 681d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * service to a {@link ListeningExecutorService}, usually by calling {@link 691d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * MoreExecutors#listeningDecorator(ExecutorService) 701d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * MoreExecutors.listeningDecorator}. (Custom executors may find it more 711d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * convenient to use {@link ListenableFutureTask} directly.) 721d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * <li>If they are manually filled in by a call to {@link FutureTask#set} or a 731d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * similar method, create a {@link SettableFuture} instead. (Users with more 741d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * complex needs may prefer {@link AbstractFuture}.) 751d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * </ul> 761d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * 770888a09821a98ac0680fad765217302858e70fa4Paul Duffin * <p>Occasionally, an API will return a plain {@code Future} and it will be 781d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * impossible to change the return type. For this case, we provide a more 791d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * expensive workaround in {@code JdkFutureAdapters}. However, when possible, it 801d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * is more efficient and reliable to create a {@code ListenableFuture} directly. 811d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * 821d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * @author Sven Mawson 831d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * @author Nishant Thakkar 841d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * @since 1.0 851d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert */ 861d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringertpublic interface ListenableFuture<V> extends Future<V> { 871d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert /** 881d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * Registers a listener to be {@linkplain Executor#execute(Runnable) run} on 891d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * the given executor. The listener will run when the {@code Future}'s 901d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * computation is {@linkplain Future#isDone() complete} or, if the computation 911d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * is already complete, immediately. 921d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * 931d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * <p>There is no guaranteed ordering of execution of listeners, but any 941d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * listener added through this method is guaranteed to be called once the 951d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * computation is complete. 961d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * 971d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * <p>Exceptions thrown by a listener will be propagated up to the executor. 981d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * Any exception thrown during {@code Executor.execute} (e.g., a {@code 991d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * RejectedExecutionException} or an exception thrown by {@linkplain 1003ecfa412eddc4b084663f38d562537b86b9734d5Paul Duffin * MoreExecutors#directExecutor direct execution}) will be caught and 1011d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * logged. 1021d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * 1031d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * <p>Note: For fast, lightweight listeners that would be safe to execute in 1043ecfa412eddc4b084663f38d562537b86b9734d5Paul Duffin * any thread, consider {@link MoreExecutors#directExecutor}. For heavier 1053ecfa412eddc4b084663f38d562537b86b9734d5Paul Duffin * listeners, {@code directExecutor()} carries some caveats. For 1067dd252788645e940eada959bdde927426e2531c9Paul Duffin * example, the listener may run on an unpredictable or undesirable thread: 1071d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * 1087dd252788645e940eada959bdde927426e2531c9Paul Duffin * <ul> 1090888a09821a98ac0680fad765217302858e70fa4Paul Duffin * <li>If this {@code Future} is done at the time {@code addListener} is 1107dd252788645e940eada959bdde927426e2531c9Paul Duffin * called, {@code addListener} will execute the listener inline. 1110888a09821a98ac0680fad765217302858e70fa4Paul Duffin * <li>If this {@code Future} is not yet done, {@code addListener} will 1120888a09821a98ac0680fad765217302858e70fa4Paul Duffin * schedule the listener to be run by the thread that completes this {@code 1130888a09821a98ac0680fad765217302858e70fa4Paul Duffin * Future}, which may be an internal system thread such as an RPC network 1140888a09821a98ac0680fad765217302858e70fa4Paul Duffin * thread. 1157dd252788645e940eada959bdde927426e2531c9Paul Duffin * </ul> 1167dd252788645e940eada959bdde927426e2531c9Paul Duffin * 1170888a09821a98ac0680fad765217302858e70fa4Paul Duffin * <p>Also note that, regardless of which thread executes the 1183ecfa412eddc4b084663f38d562537b86b9734d5Paul Duffin * {@code directExecutor()} listener, all other registered but unexecuted 1190888a09821a98ac0680fad765217302858e70fa4Paul Duffin * listeners are prevented from running during its execution, even if those 1200888a09821a98ac0680fad765217302858e70fa4Paul Duffin * listeners are to run in other executors. 1217dd252788645e940eada959bdde927426e2531c9Paul Duffin * 1227dd252788645e940eada959bdde927426e2531c9Paul Duffin * <p>This is the most general listener interface. For common operations 1237dd252788645e940eada959bdde927426e2531c9Paul Duffin * performed using listeners, see {@link 1247dd252788645e940eada959bdde927426e2531c9Paul Duffin * com.google.common.util.concurrent.Futures}. For a simplified but general 1257dd252788645e940eada959bdde927426e2531c9Paul Duffin * listener interface, see {@link 1267dd252788645e940eada959bdde927426e2531c9Paul Duffin * com.google.common.util.concurrent.Futures#addCallback addCallback()}. 1271d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * 1281d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * @param listener the listener to run when the computation is complete 1291d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * @param executor the executor to run the listener in 1301d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * @throws NullPointerException if the executor or listener was null 1311d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * @throws RejectedExecutionException if we tried to execute the listener 1321d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * immediately but the executor rejected it. 1331d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert */ 1341d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert void addListener(Runnable listener, Executor executor); 1351d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert} 136