Source for java.util.concurrent.Future

   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: }