34 */ |
34 */ |
35 |
35 |
36 package java.util.concurrent; |
36 package java.util.concurrent; |
37 |
37 |
38 /** |
38 /** |
39 * A <tt>Future</tt> represents the result of an asynchronous |
39 * A {@code Future} represents the result of an asynchronous |
40 * computation. Methods are provided to check if the computation is |
40 * computation. Methods are provided to check if the computation is |
41 * complete, to wait for its completion, and to retrieve the result of |
41 * complete, to wait for its completion, and to retrieve the result of |
42 * the computation. The result can only be retrieved using method |
42 * the computation. The result can only be retrieved using method |
43 * <tt>get</tt> when the computation has completed, blocking if |
43 * {@code get} when the computation has completed, blocking if |
44 * necessary until it is ready. Cancellation is performed by the |
44 * necessary until it is ready. Cancellation is performed by the |
45 * <tt>cancel</tt> method. Additional methods are provided to |
45 * {@code cancel} method. Additional methods are provided to |
46 * determine if the task completed normally or was cancelled. Once a |
46 * determine if the task completed normally or was cancelled. Once a |
47 * computation has completed, the computation cannot be cancelled. |
47 * computation has completed, the computation cannot be cancelled. |
48 * If you would like to use a <tt>Future</tt> for the sake |
48 * If you would like to use a {@code Future} for the sake |
49 * of cancellability but not provide a usable result, you can |
49 * of cancellability but not provide a usable result, you can |
50 * declare types of the form {@code Future<?>} and |
50 * declare types of the form {@code Future<?>} and |
51 * return <tt>null</tt> as a result of the underlying task. |
51 * return {@code null} as a result of the underlying task. |
52 * |
52 * |
53 * <p> |
53 * <p> |
54 * <b>Sample Usage</b> (Note that the following classes are all |
54 * <b>Sample Usage</b> (Note that the following classes are all |
55 * made-up.) <p> |
55 * made-up.) <p> |
56 * <pre> {@code |
56 * <pre> {@code |
70 * displayText(future.get()); // use future |
70 * displayText(future.get()); // use future |
71 * } catch (ExecutionException ex) { cleanup(); return; } |
71 * } catch (ExecutionException ex) { cleanup(); return; } |
72 * } |
72 * } |
73 * }}</pre> |
73 * }}</pre> |
74 * |
74 * |
75 * The {@link FutureTask} class is an implementation of <tt>Future</tt> that |
75 * The {@link FutureTask} class is an implementation of {@code Future} that |
76 * implements <tt>Runnable</tt>, and so may be executed by an <tt>Executor</tt>. |
76 * implements {@code Runnable}, and so may be executed by an {@code Executor}. |
77 * For example, the above construction with <tt>submit</tt> could be replaced by: |
77 * For example, the above construction with {@code submit} could be replaced by: |
78 * <pre> {@code |
78 * <pre> {@code |
79 * FutureTask<String> future = |
79 * FutureTask<String> future = |
80 * new FutureTask<String>(new Callable<String>() { |
80 * new FutureTask<String>(new Callable<String>() { |
81 * public String call() { |
81 * public String call() { |
82 * return searcher.search(target); |
82 * return searcher.search(target); |
89 * |
89 * |
90 * @see FutureTask |
90 * @see FutureTask |
91 * @see Executor |
91 * @see Executor |
92 * @since 1.5 |
92 * @since 1.5 |
93 * @author Doug Lea |
93 * @author Doug Lea |
94 * @param <V> The result type returned by this Future's <tt>get</tt> method |
94 * @param <V> The result type returned by this Future's {@code get} method |
95 */ |
95 */ |
96 public interface Future<V> { |
96 public interface Future<V> { |
97 |
97 |
98 /** |
98 /** |
99 * Attempts to cancel execution of this task. This attempt will |
99 * Attempts to cancel execution of this task. This attempt will |
100 * fail if the task has already completed, has already been cancelled, |
100 * fail if the task has already completed, has already been cancelled, |
101 * or could not be cancelled for some other reason. If successful, |
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, |
102 * and this task has not started when {@code cancel} is called, |
103 * this task should never run. If the task has already started, |
103 * this task should never run. If the task has already started, |
104 * then the <tt>mayInterruptIfRunning</tt> parameter determines |
104 * then the {@code mayInterruptIfRunning} parameter determines |
105 * whether the thread executing this task should be interrupted in |
105 * whether the thread executing this task should be interrupted in |
106 * an attempt to stop the task. |
106 * an attempt to stop the task. |
107 * |
107 * |
108 * <p>After this method returns, subsequent calls to {@link #isDone} will |
108 * <p>After this method returns, subsequent calls to {@link #isDone} will |
109 * always return <tt>true</tt>. Subsequent calls to {@link #isCancelled} |
109 * always return {@code true}. Subsequent calls to {@link #isCancelled} |
110 * will always return <tt>true</tt> if this method returned <tt>true</tt>. |
110 * will always return {@code true} if this method returned {@code true}. |
111 * |
111 * |
112 * @param mayInterruptIfRunning <tt>true</tt> if the thread executing this |
112 * @param mayInterruptIfRunning {@code true} if the thread executing this |
113 * task should be interrupted; otherwise, in-progress tasks are allowed |
113 * task should be interrupted; otherwise, in-progress tasks are allowed |
114 * to complete |
114 * to complete |
115 * @return <tt>false</tt> if the task could not be cancelled, |
115 * @return {@code false} if the task could not be cancelled, |
116 * typically because it has already completed normally; |
116 * typically because it has already completed normally; |
117 * <tt>true</tt> otherwise |
117 * {@code true} otherwise |
118 */ |
118 */ |
119 boolean cancel(boolean mayInterruptIfRunning); |
119 boolean cancel(boolean mayInterruptIfRunning); |
120 |
120 |
121 /** |
121 /** |
122 * Returns <tt>true</tt> if this task was cancelled before it completed |
122 * Returns {@code true} if this task was cancelled before it completed |
123 * normally. |
123 * normally. |
124 * |
124 * |
125 * @return <tt>true</tt> if this task was cancelled before it completed |
125 * @return {@code true} if this task was cancelled before it completed |
126 */ |
126 */ |
127 boolean isCancelled(); |
127 boolean isCancelled(); |
128 |
128 |
129 /** |
129 /** |
130 * Returns <tt>true</tt> if this task completed. |
130 * Returns {@code true} if this task completed. |
131 * |
131 * |
132 * Completion may be due to normal termination, an exception, or |
132 * Completion may be due to normal termination, an exception, or |
133 * cancellation -- in all of these cases, this method will return |
133 * cancellation -- in all of these cases, this method will return |
134 * <tt>true</tt>. |
134 * {@code true}. |
135 * |
135 * |
136 * @return <tt>true</tt> if this task completed |
136 * @return {@code true} if this task completed |
137 */ |
137 */ |
138 boolean isDone(); |
138 boolean isDone(); |
139 |
139 |
140 /** |
140 /** |
141 * Waits if necessary for the computation to complete, and then |
141 * Waits if necessary for the computation to complete, and then |