src/share/classes/java/util/concurrent/Future.java

Print this page




  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




  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