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/publicdomain/zero/1.0/
5  */
6 
7 package java.util.concurrent;
8 
9 /**
10  * A {@code Future} 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  * {@code get} when the computation has completed, blocking if
15  * necessary until it is ready.  Cancellation is performed by the
16  * {@code cancel} 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 {@code Future} for the sake
20  * of cancellability but not provide a usable result, you can
21  * declare types of the form {@code Future<?>} and
22  * return {@code null} 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> {@code
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<String> future
35  *       = executor.submit(new Callable<String>() {
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  * }}</pre>
45  *
46  * The {@link FutureTask} class is an implementation of {@code Future} that
47  * implements {@code Runnable}, and so may be executed by an {@code Executor}.
48  * For example, the above construction with {@code submit} could be replaced by:
49  *  <pre> {@code
50  * FutureTask<String> future =
51  *   new FutureTask<String>(new Callable<String>() {
52  *     public String call() {
53  *       return searcher.search(target);
54  *   }});
55  * executor.execute(future);}</pre>
56  *
57  * <p>Memory consistency effects: Actions taken by the asynchronous computation
58  * <a href="package-summary.html#MemoryVisibility"> <i>happen-before</i></a>
59  * actions following the corresponding {@code Future.get()} in another thread.
60  *
61  * @see FutureTask
62  * @see Executor
63  * @since 1.5
64  * @author Doug Lea
65  * @param <V> The result type returned by this Future's {@code get} method
66  */
67 public interface Future<V> {
68 
69     /**
70      * Attempts to cancel execution of this task.  This attempt will
71      * fail if the task has already completed, has already been cancelled,
72      * or could not be cancelled for some other reason. If successful,
73      * and this task has not started when {@code cancel} is called,
74      * this task should never run.  If the task has already started,
75      * then the {@code mayInterruptIfRunning} parameter determines
76      * whether the thread executing this task should be interrupted in
77      * an attempt to stop the task.
78      *
79      * <p>After this method returns, subsequent calls to {@link #isDone} will
80      * always return {@code true}.  Subsequent calls to {@link #isCancelled}
81      * will always return {@code true} if this method returned {@code true}.
82      *
83      * @param mayInterruptIfRunning {@code true} if the thread executing this
84      * task should be interrupted; otherwise, in-progress tasks are allowed
85      * to complete
86      * @return {@code false} if the task could not be cancelled,
87      * typically because it has already completed normally;
88      * {@code true} otherwise
89      */
cancel(boolean mayInterruptIfRunning)90     boolean cancel(boolean mayInterruptIfRunning);
91 
92     /**
93      * Returns {@code true} if this task was cancelled before it completed
94      * normally.
95      *
96      * @return {@code true} if this task was cancelled before it completed
97      */
isCancelled()98     boolean isCancelled();
99 
100     /**
101      * Returns {@code true} if this task completed.
102      *
103      * Completion may be due to normal termination, an exception, or
104      * cancellation -- in all of these cases, this method will return
105      * {@code true}.
106      *
107      * @return {@code true} if this task completed
108      */
isDone()109     boolean isDone();
110 
111     /**
112      * Waits if necessary for the computation to complete, and then
113      * retrieves its result.
114      *
115      * @return the computed result
116      * @throws CancellationException if the computation was cancelled
117      * @throws ExecutionException if the computation threw an
118      * exception
119      * @throws InterruptedException if the current thread was interrupted
120      * while waiting
121      */
get()122     V get() throws InterruptedException, ExecutionException;
123 
124     /**
125      * Waits if necessary for at most the given time for the computation
126      * to complete, and then retrieves its result, if available.
127      *
128      * @param timeout the maximum time to wait
129      * @param unit the time unit of the timeout argument
130      * @return the computed result
131      * @throws CancellationException if the computation was cancelled
132      * @throws ExecutionException if the computation threw an
133      * exception
134      * @throws InterruptedException if the current thread was interrupted
135      * while waiting
136      * @throws TimeoutException if the wait timed out
137      */
get(long timeout, TimeUnit unit)138     V get(long timeout, TimeUnit unit)
139         throws InterruptedException, ExecutionException, TimeoutException;
140 }
141