001 /*
002 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
003 *
004 * This code is free software; you can redistribute it and/or modify it
005 * under the terms of the GNU General Public License version 2 only, as
006 * published by the Free Software Foundation. Sun designates this
007 * particular file as subject to the "Classpath" exception as provided
008 * by Sun in the LICENSE file that accompanied this code.
009 *
010 * This code is distributed in the hope that it will be useful, but WITHOUT
011 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
012 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
013 * version 2 for more details (a copy is included in the LICENSE file that
014 * accompanied this code).
015 *
016 * You should have received a copy of the GNU General Public License version
017 * 2 along with this work; if not, write to the Free Software Foundation,
018 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
019 *
020 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
021 * CA 95054 USA or visit www.sun.com if you need additional information or
022 * have any questions.
023 */
024
025 /*
026 * This file is available under and governed by the GNU General Public
027 * License version 2 only, as published by the Free Software Foundation.
028 * However, the following notice accompanied the original version of this
029 * file:
030 *
031 * Written by Doug Lea with assistance from members of JCP JSR-166
032 * Expert Group and released to the public domain, as explained at
033 * http://creativecommons.org/licenses/publicdomain
034 */
035
036 package java.util.concurrent;
037
038 /**
039 * A <tt>Future</tt> represents the result of an asynchronous
040 * computation. Methods are provided to check if the computation is
041 * complete, to wait for its completion, and to retrieve the result of
042 * the computation. The result can only be retrieved using method
043 * <tt>get</tt> when the computation has completed, blocking if
044 * necessary until it is ready. Cancellation is performed by the
045 * <tt>cancel</tt> method. Additional methods are provided to
046 * determine if the task completed normally or was cancelled. Once a
047 * computation has completed, the computation cannot be cancelled.
048 * If you would like to use a <tt>Future</tt> for the sake
049 * of cancellability but not provide a usable result, you can
050 * declare types of the form <tt>Future<?></tt> and
051 * return <tt>null</tt> as a result of the underlying task.
052 *
053 * <p>
054 * <b>Sample Usage</b> (Note that the following classes are all
055 * made-up.) <p>
056 * <pre>
057 * interface ArchiveSearcher { String search(String target); }
058 * class App {
059 * ExecutorService executor = ...
060 * ArchiveSearcher searcher = ...
061 * void showSearch(final String target)
062 * throws InterruptedException {
063 * Future<String> future
064 * = executor.submit(new Callable<String>() {
065 * public String call() {
066 * return searcher.search(target);
067 * }});
068 * displayOtherThings(); // do other things while searching
069 * try {
070 * displayText(future.get()); // use future
071 * } catch (ExecutionException ex) { cleanup(); return; }
072 * }
073 * }
074 * </pre>
075 *
076 * The {@link FutureTask} class is an implementation of <tt>Future</tt> that
077 * implements <tt>Runnable</tt>, and so may be executed by an <tt>Executor</tt>.
078 * For example, the above construction with <tt>submit</tt> could be replaced by:
079 * <pre>
080 * FutureTask<String> future =
081 * new FutureTask<String>(new Callable<String>() {
082 * public String call() {
083 * return searcher.search(target);
084 * }});
085 * executor.execute(future);
086 * </pre>
087 *
088 * <p>Memory consistency effects: Actions taken by the asynchronous computation
089 * <a href="package-summary.html#MemoryVisibility"> <i>happen-before</i></a>
090 * actions following the corresponding {@code Future.get()} in another thread.
091 *
092 * @see FutureTask
093 * @see Executor
094 * @since 1.5
095 * @author Doug Lea
096 * @param <V> The result type returned by this Future's <tt>get</tt> method
097 */
098 public interface Future<V> {
099
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
107 * whether the thread executing this task should be interrupted in
108 * an attempt to stop the task.
109 *
110 * <p>After this method returns, subsequent calls to {@link #isDone} will
111 * always return <tt>true</tt>. Subsequent calls to {@link #isCancelled}
112 * will always return <tt>true</tt> if this method returned <tt>true</tt>.
113 *
114 * @param mayInterruptIfRunning <tt>true</tt> if the thread executing this
115 * task should be interrupted; otherwise, in-progress tasks are allowed
116 * to complete
117 * @return <tt>false</tt> if the task could not be cancelled,
118 * typically because it has already completed normally;
119 * <tt>true</tt> otherwise
120 */
121 boolean cancel(boolean mayInterruptIfRunning);
122
123 /**
124 * Returns <tt>true</tt> if this task was cancelled before it completed
125 * normally.
126 *
127 * @return <tt>true</tt> if this task was cancelled before it completed
128 */
129 boolean isCancelled();
130
131 /**
132 * Returns <tt>true</tt> if this task completed.
133 *
134 * Completion may be due to normal termination, an exception, or
135 * cancellation -- in all of these cases, this method will return
136 * <tt>true</tt>.
137 *
138 * @return <tt>true</tt> if this task completed
139 */
140 boolean isDone();
141
142 /**
143 * Waits if necessary for the computation to complete, and then
144 * retrieves its result.
145 *
146 * @return the computed result
147 * @throws CancellationException if the computation was cancelled
148 * @throws ExecutionException if the computation threw an
149 * exception
150 * @throws InterruptedException if the current thread was interrupted
151 * while waiting
152 */
153 V get() throws InterruptedException, ExecutionException;
154
155 /**
156 * Waits if necessary for at most the given time for the computation
157 * to complete, and then retrieves its result, if available.
158 *
159 * @param timeout the maximum time to wait
160 * @param unit the time unit of the timeout argument
161 * @return the computed result
162 * @throws CancellationException if the computation was cancelled
163 * @throws ExecutionException if the computation threw an
164 * exception
165 * @throws InterruptedException if the current thread was interrupted
166 * while waiting
167 * @throws TimeoutException if the wait timed out
168 */
169 V get(long timeout, TimeUnit unit) throws InterruptedException,
170 ExecutionException, TimeoutException;
171 }
|