jaroslav@1890: /* jaroslav@1890: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. jaroslav@1890: * jaroslav@1890: * This code is free software; you can redistribute it and/or modify it jaroslav@1890: * under the terms of the GNU General Public License version 2 only, as jaroslav@1890: * published by the Free Software Foundation. Oracle designates this jaroslav@1890: * particular file as subject to the "Classpath" exception as provided jaroslav@1890: * by Oracle in the LICENSE file that accompanied this code. jaroslav@1890: * jaroslav@1890: * This code is distributed in the hope that it will be useful, but WITHOUT jaroslav@1890: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or jaroslav@1890: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License jaroslav@1890: * version 2 for more details (a copy is included in the LICENSE file that jaroslav@1890: * accompanied this code). jaroslav@1890: * jaroslav@1890: * You should have received a copy of the GNU General Public License version jaroslav@1890: * 2 along with this work; if not, write to the Free Software Foundation, jaroslav@1890: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. jaroslav@1890: * jaroslav@1890: * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA jaroslav@1890: * or visit www.oracle.com if you need additional information or have any jaroslav@1890: * questions. jaroslav@1890: */ jaroslav@1890: jaroslav@1890: /* jaroslav@1890: * This file is available under and governed by the GNU General Public jaroslav@1890: * License version 2 only, as published by the Free Software Foundation. jaroslav@1890: * However, the following notice accompanied the original version of this jaroslav@1890: * file: jaroslav@1890: * jaroslav@1890: * Written by Doug Lea with assistance from members of JCP JSR-166 jaroslav@1890: * Expert Group and released to the public domain, as explained at jaroslav@1890: * http://creativecommons.org/publicdomain/zero/1.0/ jaroslav@1890: */ jaroslav@1890: jaroslav@1890: package java.util.concurrent; jaroslav@1890: jaroslav@1890: /** jaroslav@1890: * A Future represents the result of an asynchronous jaroslav@1890: * computation. Methods are provided to check if the computation is jaroslav@1890: * complete, to wait for its completion, and to retrieve the result of jaroslav@1890: * the computation. The result can only be retrieved using method jaroslav@1890: * get when the computation has completed, blocking if jaroslav@1890: * necessary until it is ready. Cancellation is performed by the jaroslav@1890: * cancel method. Additional methods are provided to jaroslav@1890: * determine if the task completed normally or was cancelled. Once a jaroslav@1890: * computation has completed, the computation cannot be cancelled. jaroslav@1890: * If you would like to use a Future for the sake jaroslav@1890: * of cancellability but not provide a usable result, you can jaroslav@1890: * declare types of the form {@code Future} and jaroslav@1890: * return null as a result of the underlying task. jaroslav@1890: * jaroslav@1890: *

jaroslav@1890: * Sample Usage (Note that the following classes are all jaroslav@1890: * made-up.)

jaroslav@1890: * 

 {@code
jaroslav@1890:  * interface ArchiveSearcher { String search(String target); }
jaroslav@1890:  * class App {
jaroslav@1890:  *   ExecutorService executor = ...
jaroslav@1890:  *   ArchiveSearcher searcher = ...
jaroslav@1890:  *   void showSearch(final String target)
jaroslav@1890:  *       throws InterruptedException {
jaroslav@1890:  *     Future future
jaroslav@1890:  *       = executor.submit(new Callable() {
jaroslav@1890:  *         public String call() {
jaroslav@1890:  *             return searcher.search(target);
jaroslav@1890:  *         }});
jaroslav@1890:  *     displayOtherThings(); // do other things while searching
jaroslav@1890:  *     try {
jaroslav@1890:  *       displayText(future.get()); // use future
jaroslav@1890:  *     } catch (ExecutionException ex) { cleanup(); return; }
jaroslav@1890:  *   }
jaroslav@1890:  * }}
jaroslav@1890: * jaroslav@1890: * The {@link FutureTask} class is an implementation of Future that jaroslav@1890: * implements Runnable, and so may be executed by an Executor. jaroslav@1890: * For example, the above construction with submit could be replaced by: jaroslav@1890: * 
 {@code
jaroslav@1890:  *     FutureTask future =
jaroslav@1890:  *       new FutureTask(new Callable() {
jaroslav@1890:  *         public String call() {
jaroslav@1890:  *           return searcher.search(target);
jaroslav@1890:  *       }});
jaroslav@1890:  *     executor.execute(future);}
jaroslav@1890: * jaroslav@1890: *

Memory consistency effects: Actions taken by the asynchronous computation jaroslav@1890: * happen-before jaroslav@1890: * actions following the corresponding {@code Future.get()} in another thread. jaroslav@1890: * jaroslav@1890: * @see FutureTask jaroslav@1890: * @see Executor jaroslav@1890: * @since 1.5 jaroslav@1890: * @author Doug Lea jaroslav@1890: * @param The result type returned by this Future's get method jaroslav@1890: */ jaroslav@1890: public interface Future { jaroslav@1890: jaroslav@1890: /** jaroslav@1890: * Attempts to cancel execution of this task. This attempt will jaroslav@1890: * fail if the task has already completed, has already been cancelled, jaroslav@1890: * or could not be cancelled for some other reason. If successful, jaroslav@1890: * and this task has not started when cancel is called, jaroslav@1890: * this task should never run. If the task has already started, jaroslav@1890: * then the mayInterruptIfRunning parameter determines jaroslav@1890: * whether the thread executing this task should be interrupted in jaroslav@1890: * an attempt to stop the task. jaroslav@1890: * jaroslav@1890: *

After this method returns, subsequent calls to {@link #isDone} will jaroslav@1890: * always return true. Subsequent calls to {@link #isCancelled} jaroslav@1890: * will always return true if this method returned true. jaroslav@1890: * jaroslav@1890: * @param mayInterruptIfRunning true if the thread executing this jaroslav@1890: * task should be interrupted; otherwise, in-progress tasks are allowed jaroslav@1890: * to complete jaroslav@1890: * @return false if the task could not be cancelled, jaroslav@1890: * typically because it has already completed normally; jaroslav@1890: * true otherwise jaroslav@1890: */ jaroslav@1890: boolean cancel(boolean mayInterruptIfRunning); jaroslav@1890: jaroslav@1890: /** jaroslav@1890: * Returns true if this task was cancelled before it completed jaroslav@1890: * normally. jaroslav@1890: * jaroslav@1890: * @return true if this task was cancelled before it completed jaroslav@1890: */ jaroslav@1890: boolean isCancelled(); jaroslav@1890: jaroslav@1890: /** jaroslav@1890: * Returns true if this task completed. jaroslav@1890: * jaroslav@1890: * Completion may be due to normal termination, an exception, or jaroslav@1890: * cancellation -- in all of these cases, this method will return jaroslav@1890: * true. jaroslav@1890: * jaroslav@1890: * @return true if this task completed jaroslav@1890: */ jaroslav@1890: boolean isDone(); jaroslav@1890: jaroslav@1890: /** jaroslav@1890: * Waits if necessary for the computation to complete, and then jaroslav@1890: * retrieves its result. jaroslav@1890: * jaroslav@1890: * @return the computed result jaroslav@1890: * @throws CancellationException if the computation was cancelled jaroslav@1890: * @throws ExecutionException if the computation threw an jaroslav@1890: * exception jaroslav@1890: * @throws InterruptedException if the current thread was interrupted jaroslav@1890: * while waiting jaroslav@1890: */ jaroslav@1890: V get() throws InterruptedException, ExecutionException; jaroslav@1890: jaroslav@1890: /** jaroslav@1890: * Waits if necessary for at most the given time for the computation jaroslav@1890: * to complete, and then retrieves its result, if available. jaroslav@1890: * jaroslav@1890: * @param timeout the maximum time to wait jaroslav@1890: * @param unit the time unit of the timeout argument jaroslav@1890: * @return the computed result jaroslav@1890: * @throws CancellationException if the computation was cancelled jaroslav@1890: * @throws ExecutionException if the computation threw an jaroslav@1890: * exception jaroslav@1890: * @throws InterruptedException if the current thread was interrupted jaroslav@1890: * while waiting jaroslav@1890: * @throws TimeoutException if the wait timed out jaroslav@1890: */ jaroslav@1890: V get(long timeout, TimeUnit unit) jaroslav@1890: throws InterruptedException, ExecutionException, TimeoutException; jaroslav@1890: }