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 <tt>Future&lt;?&gt;</tt> 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>
  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&lt;String&gt; future
  64  *       = executor.submit(new Callable&lt;String&gt;() {
  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  * }
  74  * </pre>
  75  *
  76  * The {@link FutureTask} class is an implementation of <tt>Future</tt> that
  77  * implements <tt>Runnable</tt>, and so may be executed by an <tt>Executor</tt>.
  78  * For example, the above construction with <tt>submit</tt> could be replaced by:
  79  * <pre>
  80  *     FutureTask&lt;String&gt; future =
  81  *       new FutureTask&lt;String&gt;(new Callable&lt;String&gt;() {
  82  *         public String call() {
  83  *           return searcher.search(target);
  84  *       }});
  85  *     executor.execute(future);
  86  * </pre>
  87  *
  88  * <p>Memory consistency effects: Actions taken by the asynchronous computation
  89  * <a href="package-summary.html#MemoryVisibility"> <i>happen-before</i></a>
  90  * actions following the corresponding {@code Future.get()} in another thread.
  91  *
  92  * @see FutureTask
  93  * @see Executor
  94  * @since 1.5
  95  * @author Doug Lea
  96  * @param <V> The result type returned by this Future's <tt>get</tt> method
  97  */
  98 public interface Future<V> {
  99 
 100     /**
 101      * Attempts to cancel execution of this task.  This attempt will
 102      * fail if the task has already completed, has already been cancelled,
 103      * or could not be cancelled for some other reason. If successful,
 104      * and this task has not started when <tt>cancel</tt> is called,
 105      * this task should never run.  If the task has already started,
 106      * then the <tt>mayInterruptIfRunning</tt> parameter determines
 107      * whether the thread executing this task should be interrupted in
 108      * an attempt to stop the task.
 109      *
 110      * <p>After this method returns, subsequent calls to {@link #isDone} will
 111      * always return <tt>true</tt>.  Subsequent calls to {@link #isCancelled}
 112      * will always return <tt>true</tt> if this method returned <tt>true</tt>.
 113      *
 114      * @param mayInterruptIfRunning <tt>true</tt> if the thread executing this
 115      * task should be interrupted; otherwise, in-progress tasks are allowed
 116      * to complete
 117      * @return <tt>false</tt> if the task could not be cancelled,
 118      * typically because it has already completed normally;
 119      * <tt>true</tt> otherwise
 120      */
 121     boolean cancel(boolean mayInterruptIfRunning);
 122 
 123     /**
 124      * Returns <tt>true</tt> if this task was cancelled before it completed
 125      * normally.
 126      *
 127      * @return <tt>true</tt> if this task was cancelled before it completed
 128      */
 129     boolean isCancelled();
 130 
 131     /**
 132      * Returns <tt>true</tt> if this task completed.
 133      *
 134      * Completion may be due to normal termination, an exception, or
 135      * cancellation -- in all of these cases, this method will return
 136      * <tt>true</tt>.
 137      *
 138      * @return <tt>true</tt> if this task completed
 139      */
 140     boolean isDone();
 141 
 142     /**
 143      * Waits if necessary for the computation to complete, and then
 144      * retrieves its result.
 145      *
 146      * @return the computed result
 147      * @throws CancellationException if the computation was cancelled
 148      * @throws ExecutionException if the computation threw an
 149      * exception
 150      * @throws InterruptedException if the current thread was interrupted
 151      * while waiting
 152      */
 153     V get() throws InterruptedException, ExecutionException;
 154 
 155     /**
 156      * Waits if necessary for at most the given time for the computation
 157      * to complete, and then retrieves its result, if available.
 158      *
 159      * @param timeout the maximum time to wait
 160      * @param unit the time unit of the timeout argument
 161      * @return the computed result
 162      * @throws CancellationException if the computation was cancelled
 163      * @throws ExecutionException if the computation threw an
 164      * exception
 165      * @throws InterruptedException if the current thread was interrupted
 166      * while waiting
 167      * @throws TimeoutException if the wait timed out
 168      */
 169     V get(long timeout, TimeUnit unit)
 170         throws InterruptedException, ExecutionException, TimeoutException;
 171 }