|
|
@@ -0,0 +1,50 @@
|
|
|
+/**
|
|
|
+ * A {@code Future} represents the result of an asynchronous
|
|
|
+ * computation. Methods are provided to check if the computation is
|
|
|
+ * complete, to wait for its completion, and to retrieve the result of
|
|
|
+ * the computation. The result can only be retrieved using method
|
|
|
+ * {@code get} when the computation has completed, blocking if
|
|
|
+ * necessary until it is ready. Cancellation is performed by the
|
|
|
+ * {@code cancel} method. Additional methods are provided to
|
|
|
+ * determine if the task completed normally or was cancelled. Once a
|
|
|
+ * computation has completed, the computation cannot be cancelled.
|
|
|
+ * If you would like to use a {@code Future} for the sake
|
|
|
+ * of cancellability but not provide a usable result, you can
|
|
|
+ * declare types of the form {@code Future<?>} and
|
|
|
+ * return {@code null} as a result of the underlying task.
|
|
|
+ *
|
|
|
+ * <p><b>Sample Usage</b> (Note that the following classes are all
|
|
|
+ * made-up.)
|
|
|
+ *
|
|
|
+ * <pre> {@code
|
|
|
+ * interface ArchiveSearcher { String search(String target); }
|
|
|
+ * class App {
|
|
|
+ * ExecutorService executor = ...;
|
|
|
+ * ArchiveSearcher searcher = ...;
|
|
|
+ * void showSearch(String target) throws InterruptedException {
|
|
|
+ * Callable<String> task = () -> searcher.search(target);
|
|
|
+ * Future<String> future = executor.submit(task);
|
|
|
+ * displayOtherThings(); // do other things while searching
|
|
|
+ * try {
|
|
|
+ * displayText(future.get()); // use future
|
|
|
+ * } catch (ExecutionException ex) { cleanup(); return; }
|
|
|
+ * }
|
|
|
+ * }}</pre>
|
|
|
+ *
|
|
|
+ * The {@link FutureTask} class is an implementation of {@code Future} that
|
|
|
+ * implements {@code Runnable}, and so may be executed by an {@code Executor}.
|
|
|
+ * For example, the above construction with {@code submit} could be replaced by:
|
|
|
+ * <pre> {@code
|
|
|
+ * FutureTask<String> future = new FutureTask<>(task);
|
|
|
+ * executor.execute(future);}</pre>
|
|
|
+ *
|
|
|
+ * <p>Memory consistency effects: Actions taken by the asynchronous computation
|
|
|
+ * <a href="package-summary.html#MemoryVisibility"> <i>happen-before</i></a>
|
|
|
+ * actions following the corresponding {@code Future.get()} in another thread.
|
|
|
+ *
|
|
|
+ * @see FutureTask
|
|
|
+ * @see Executor
|
|
|
+ * @since 1.5
|
|
|
+ * @author Doug Lea
|
|
|
+ * @param <V> The result type returned by this Future's {@code get} method
|
|
|
+ */
|