1 /*
   2  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   3  *
   4  * This code is free software; you can redistribute it and/or modify it
   5  * under the terms of the GNU General Public License version 2 only, as
   6  * published by the Free Software Foundation.  Oracle designates this
   7  * particular file as subject to the "Classpath" exception as provided
   8  * by Oracle in the LICENSE file that accompanied this code.
   9  *
  10  * This code is distributed in the hope that it will be useful, but WITHOUT
  11  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  12  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  13  * version 2 for more details (a copy is included in the LICENSE file that
  14  * accompanied this code).
  15  *
  16  * You should have received a copy of the GNU General Public License version
  17  * 2 along with this work; if not, write to the Free Software Foundation,
  18  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  19  *
  20  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  21  * or visit www.oracle.com if you need additional information or have any
  22  * questions.
  23  */
  24 
  25 /*
  26  * This file is available under and governed by the GNU General Public
  27  * License version 2 only, as published by the Free Software Foundation.
  28  * However, the following notice accompanied the original version of this
  29  * file:
  30  *
  31  * Written by Doug Lea with assistance from members of JCP JSR-166
  32  * Expert Group and released to the public domain, as explained at
  33  * http://creativecommons.org/licenses/publicdomain
  34  */
  35 
  36 package java.util.concurrent;
  37 
  38 /**
  39  * A <tt>Future</tt> represents the result of an asynchronous
  40  * computation.  Methods are provided to check if the computation is
  41  * complete, to wait for its completion, and to retrieve the result of
  42  * the computation.  The result can only be retrieved using method
  43  * <tt>get</tt> when the computation has completed, blocking if
  44  * necessary until it is ready.  Cancellation is performed by the
  45  * <tt>cancel</tt> method.  Additional methods are provided to
  46  * determine if the task completed normally or was cancelled. Once a
  47  * computation has completed, the computation cannot be cancelled.
  48  * If you would like to use a <tt>Future</tt> for the sake
  49  * of cancellability but not provide a usable result, you can
  50  * declare types of the form {@code Future<?>} and
  51  * return <tt>null</tt> as a result of the underlying task.
  52  *
  53  * <p>
  54  * <b>Sample Usage</b> (Note that the following classes are all
  55  * made-up.) <p>
  56  *  <pre> {@code
  57  * interface ArchiveSearcher { String search(String target); }
  58  * class App {
  59  *   ExecutorService executor = ...
  60  *   ArchiveSearcher searcher = ...
  61  *   void showSearch(final String target)
  62  *       throws InterruptedException {
  63  *     Future<String> future
  64  *       = executor.submit(new Callable<String>() {
  65  *         public String call() {
  66  *             return searcher.search(target);
  67  *         }});
  68  *     displayOtherThings(); // do other things while searching
  69  *     try {
  70  *       displayText(future.get()); // use future
  71  *     } catch (ExecutionException ex) { cleanup(); return; }
  72  *   }
  73  * }}</pre>
  74  *
  75  * The {@link FutureTask} class is an implementation of <tt>Future</tt> that
  76  * implements <tt>Runnable</tt>, and so may be executed by an <tt>Executor</tt>.
  77  * For example, the above construction with <tt>submit</tt> could be replaced by:
  78  *  <pre> {@code
  79  *     FutureTask<String> future =
  80  *       new FutureTask<String>(new Callable<String>() {
  81  *         public String call() {
  82  *           return searcher.search(target);
  83  *       }});
  84  *     executor.execute(future);}</pre>
  85  *
  86  * <p>Memory consistency effects: Actions taken by the asynchronous computation
  87  * <a href="package-summary.html#MemoryVisibility"> <i>happen-before</i></a>
  88  * actions following the corresponding {@code Future.get()} in another thread.
  89  *
  90  * @see FutureTask
  91  * @see Executor
  92  * @since 1.5
  93  * @author Doug Lea
  94  * @param <V> The result type returned by this Future's <tt>get</tt> method
  95  */
  96 public interface Future<V> {
  97 
  98     /**
  99      * Attempts to cancel execution of this task.  This attempt will
 100      * fail if the task has already completed, has already been cancelled,
 101      * or could not be cancelled for some other reason. If successful,
 102      * and this task has not started when <tt>cancel</tt> is called,
 103      * this task should never run.  If the task has already started,
 104      * then the <tt>mayInterruptIfRunning</tt> parameter determines
 105      * whether the thread executing this task should be interrupted in
 106      * an attempt to stop the task.
 107      *
 108      * <p>After this method returns, subsequent calls to {@link #isDone} will
 109      * always return <tt>true</tt>.  Subsequent calls to {@link #isCancelled}
 110      * will always return <tt>true</tt> if this method returned <tt>true</tt>.
 111      *
 112      * @param mayInterruptIfRunning <tt>true</tt> if the thread executing this
 113      * task should be interrupted; otherwise, in-progress tasks are allowed
 114      * to complete
 115      * @return <tt>false</tt> if the task could not be cancelled,
 116      * typically because it has already completed normally;
 117      * <tt>true</tt> otherwise
 118      */
 119     boolean cancel(boolean mayInterruptIfRunning);
 120 
 121     /**
 122      * Returns <tt>true</tt> if this task was cancelled before it completed
 123      * normally.
 124      *
 125      * @return <tt>true</tt> if this task was cancelled before it completed
 126      */
 127     boolean isCancelled();
 128 
 129     /**
 130      * Returns <tt>true</tt> if this task completed.
 131      *
 132      * Completion may be due to normal termination, an exception, or
 133      * cancellation -- in all of these cases, this method will return
 134      * <tt>true</tt>.
 135      *
 136      * @return <tt>true</tt> if this task completed
 137      */
 138     boolean isDone();
 139 
 140     /**
 141      * Waits if necessary for the computation to complete, and then
 142      * retrieves its result.
 143      *
 144      * @return the computed result
 145      * @throws CancellationException if the computation was cancelled
 146      * @throws ExecutionException if the computation threw an
 147      * exception
 148      * @throws InterruptedException if the current thread was interrupted
 149      * while waiting
 150      */
 151     V get() throws InterruptedException, ExecutionException;
 152 
 153     /**
 154      * Waits if necessary for at most the given time for the computation
 155      * to complete, and then retrieves its result, if available.
 156      *
 157      * @param timeout the maximum time to wait
 158      * @param unit the time unit of the timeout argument
 159      * @return the computed result
 160      * @throws CancellationException if the computation was cancelled
 161      * @throws ExecutionException if the computation threw an
 162      * exception
 163      * @throws InterruptedException if the current thread was interrupted
 164      * while waiting
 165      * @throws TimeoutException if the wait timed out
 166      */
 167     V get(long timeout, TimeUnit unit)
 168         throws InterruptedException, ExecutionException, TimeoutException;
 169 }