lib/classpath/external/jsr166/java/util/concurrent/Future.java

   1 /*
   2  * Written by Doug Lea with assistance from members of JCP JSR-166
   3  * Expert Group and released to the public domain, as explained at
   4  * http://creativecommons.org/licenses/publicdomain
   5  */
   6
   7 package java.util.concurrent;
   8
   9 /**
  10  * A <tt>Future</tt> represents the result of an asynchronous
  11  * computation.  Methods are provided to check if the computation is
  12  * complete, to wait for its completion, and to retrieve the result of
  13  * the computation.  The result can only be retrieved using method
  14  * <tt>get</tt> when the computation has completed, blocking if
  15  * necessary until it is ready.  Cancellation is performed by the
  16  * <tt>cancel</tt> method.  Additional methods are provided to
  17  * determine if the task completed normally or was cancelled. Once a
  18  * computation has completed, the computation cannot be cancelled.
  19  * If you would like to use a <tt>Future</tt> for the sake
  20  * of cancellability but not provide a usable result, you can
  21  * declare types of the form <tt>Future&lt;?&gt;</tt> and
  22  * return <tt>null</tt> as a result of the underlying task.
  23  *
  24  * <p>
  25  * <b>Sample Usage</b> (Note that the following classes are all
  26  * made-up.) <p>
  27  * <pre>
  28  * interface ArchiveSearcher { String search(String target); }
  29  * class App {
  30  *   ExecutorService executor = ...
  31  *   ArchiveSearcher searcher = ...
  32  *   void showSearch(final String target)
  33  *       throws InterruptedException {
  34  *     Future&lt;String&gt; future
  35  *       = executor.submit(new Callable&lt;String&gt;() {
  36  *         public String call() {
  37  *             return searcher.search(target);
  38  *         }});
  39  *     displayOtherThings(); // do other things while searching
  40  *     try {
  41  *       displayText(future.get()); // use future
  42  *     } catch (ExecutionException ex) { cleanup(); return; }
  43  *   }
  44  * }
  45  * </pre>
  46  *
  47  * The {@link FutureTask} class is an implementation of <tt>Future</tt> that
  48  * implements <tt>Runnable</tt>, and so may be executed by an <tt>Executor</tt>.
  49  * For example, the above construction with <tt>submit</tt> could be replaced by:
  50  * <pre>
  51  *     FutureTask&lt;String&gt; future =
  52  *       new FutureTask&lt;String&gt;(new Callable&lt;String&gt;() {
  53  *         public String call() {
  54  *           return searcher.search(target);
  55  *       }});
  56  *     executor.execute(future);
  57  * </pre>
  58  *
  59  * <p>Memory consistency effects: Actions taken by the asynchronous computation
  60  * <a href="package-summary.html#MemoryVisibility"> <i>happen-before</i></a>
  61  * actions following the corresponding {@code Future.get()} in another thread.
  62  *
  63  * @see FutureTask
  64  * @see Executor
  65  * @since 1.5
  66  * @author Doug Lea
  67  * @param <V> The result type returned by this Future's <tt>get</tt> method
  68  */
  69 public interface Future<V> {
  70
  71     /**
  72      * Attempts to cancel execution of this task.  This attempt will
  73      * fail if the task has already completed, has already been cancelled,
  74      * or could not be cancelled for some other reason. If successful,
  75      * and this task has not started when <tt>cancel</tt> is called,
  76      * this task should never run.  If the task has already started,
  77      * then the <tt>mayInterruptIfRunning</tt> parameter determines
  78      * whether the thread executing this task should be interrupted in
  79      * an attempt to stop the task.
  80      *
  81      * <p>After this method returns, subsequent calls to {@link #isDone} will
  82      * always return <tt>true</tt>.  Subsequent calls to {@link #isCancelled}
  83      * will always return <tt>true</tt> if this method returned <tt>true</tt>.
  84      *
  85      * @param mayInterruptIfRunning <tt>true</tt> if the thread executing this
  86      * task should be interrupted; otherwise, in-progress tasks are allowed
  87      * to complete
  88      * @return <tt>false</tt> if the task could not be cancelled,
  89      * typically because it has already completed normally;
  90      * <tt>true</tt> otherwise
  91      */
  92     boolean cancel(boolean mayInterruptIfRunning);
  93
  94     /**
  95      * Returns <tt>true</tt> if this task was cancelled before it completed
  96      * normally.
  97      *
  98      * @return <tt>true</tt> if this task was cancelled before it completed
  99      */
 100     boolean isCancelled();
 101
 102     /**
 103      * Returns <tt>true</tt> if this task completed.
 104      *
 105      * Completion may be due to normal termination, an exception, or
 106      * cancellation -- in all of these cases, this method will return
 107      * <tt>true</tt>.
 108      *
 109      * @return <tt>true</tt> if this task completed
 110      */
 111     boolean isDone();
 112
 113     /**
 114      * Waits if necessary for the computation to complete, and then
 115      * retrieves its result.
 116      *
 117      * @return the computed result
 118      * @throws CancellationException if the computation was cancelled
 119      * @throws ExecutionException if the computation threw an
 120      * exception
 121      * @throws InterruptedException if the current thread was interrupted
 122      * while waiting
 123      */
 124     V get() throws InterruptedException, ExecutionException;
 125
 126     /**
 127      * Waits if necessary for at most the given time for the computation
 128      * to complete, and then retrieves its result, if available.
 129      *
 130      * @param timeout the maximum time to wait
 131      * @param unit the time unit of the timeout argument
 132      * @return the computed result
 133      * @throws CancellationException if the computation was cancelled
 134      * @throws ExecutionException if the computation threw an
 135      * exception
 136      * @throws InterruptedException if the current thread was interrupted
 137      * while waiting
 138      * @throws TimeoutException if the wait timed out
 139      */
 140     V get(long timeout, TimeUnit unit)
 141         throws InterruptedException, ExecutionException, TimeoutException;
 142 }