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/licenses/publicdomain
7 package java.util.concurrent;
8 import java.util.concurrent.locks.*;
11 * A cancellable asynchronous computation. This class provides a base
12 * implementation of {@link Future}, with methods to start and cancel
13 * a computation, query to see if the computation is complete, and
14 * retrieve the result of the computation. The result can only be
15 * retrieved when the computation has completed; the <tt>get</tt>
16 * method will block if the computation has not yet completed. Once
17 * the computation has completed, the computation cannot be restarted
20 * <p>A <tt>FutureTask</tt> can be used to wrap a {@link Callable} or
21 * {@link java.lang.Runnable} object. Because <tt>FutureTask</tt>
22 * implements <tt>Runnable</tt>, a <tt>FutureTask</tt> can be
23 * submitted to an {@link Executor} for execution.
25 * <p>In addition to serving as a standalone class, this class provides
26 * <tt>protected</tt> functionality that may be useful when creating
27 * customized task classes.
31 * @param <V> The result type returned by this FutureTask's <tt>get</tt> method
33 public class FutureTask<V> implements RunnableFuture<V> {
34 /** Synchronization control for FutureTask */
35 private final Sync sync;
38 * Creates a <tt>FutureTask</tt> that will upon running, execute the
39 * given <tt>Callable</tt>.
41 * @param callable the callable task
42 * @throws NullPointerException if callable is null
44 public FutureTask(Callable<V> callable) {
46 throw new NullPointerException();
47 sync = new Sync(callable);
51 * Creates a <tt>FutureTask</tt> that will upon running, execute the
52 * given <tt>Runnable</tt>, and arrange that <tt>get</tt> will return the
53 * given result on successful completion.
55 * @param runnable the runnable task
56 * @param result the result to return on successful completion. If
57 * you don't need a particular result, consider using
58 * constructions of the form:
59 * <tt>Future<?> f = new FutureTask<Object>(runnable, null)</tt>
60 * @throws NullPointerException if runnable is null
62 public FutureTask(Runnable runnable, V result) {
63 sync = new Sync(Executors.callable(runnable, result));
66 public boolean isCancelled() {
67 return sync.innerIsCancelled();
70 public boolean isDone() {
71 return sync.innerIsDone();
74 public boolean cancel(boolean mayInterruptIfRunning) {
75 return sync.innerCancel(mayInterruptIfRunning);
79 * @throws CancellationException {@inheritDoc}
81 public V get() throws InterruptedException, ExecutionException {
82 return sync.innerGet();
86 * @throws CancellationException {@inheritDoc}
88 public V get(long timeout, TimeUnit unit)
89 throws InterruptedException, ExecutionException, TimeoutException {
90 return sync.innerGet(unit.toNanos(timeout));
94 * Protected method invoked when this task transitions to state
95 * <tt>isDone</tt> (whether normally or via cancellation). The
96 * default implementation does nothing. Subclasses may override
97 * this method to invoke completion callbacks or perform
98 * bookkeeping. Note that you can query status inside the
99 * implementation of this method to determine whether this task
100 * has been cancelled.
102 protected void done() { }
105 * Sets the result of this Future to the given value unless
106 * this future has already been set or has been cancelled.
107 * This method is invoked internally by the <tt>run</tt> method
108 * upon successful completion of the computation.
111 protected void set(V v) {
116 * Causes this future to report an <tt>ExecutionException</tt>
117 * with the given throwable as its cause, unless this Future has
118 * already been set or has been cancelled.
119 * This method is invoked internally by the <tt>run</tt> method
120 * upon failure of the computation.
121 * @param t the cause of failure
123 protected void setException(Throwable t) {
124 sync.innerSetException(t);
127 // The following (duplicated) doc comment can be removed once
129 // 6270645: Javadoc comments should be inherited from most derived
130 // superinterface or superclass
133 * Sets this Future to the result of its computation
134 * unless it has been cancelled.
141 * Executes the computation without setting its result, and then
142 * resets this Future to initial state, failing to do so if the
143 * computation encounters an exception or is cancelled. This is
144 * designed for use with tasks that intrinsically execute more
146 * @return true if successfully run and reset
148 protected boolean runAndReset() {
149 return sync.innerRunAndReset();
153 * Synchronization control for FutureTask. Note that this must be
154 * a non-static inner class in order to invoke the protected
155 * <tt>done</tt> method. For clarity, all inner class support
156 * methods are same as outer, prefixed with "inner".
158 * Uses AQS sync state to represent run status
160 private final class Sync extends AbstractQueuedSynchronizer {
161 private static final long serialVersionUID = -7828117401763700385L;
163 /** State value representing that task is running */
164 private static final int RUNNING = 1;
165 /** State value representing that task ran */
166 private static final int RAN = 2;
167 /** State value representing that task was cancelled */
168 private static final int CANCELLED = 4;
170 /** The underlying callable */
171 private final Callable<V> callable;
172 /** The result to return from get() */
174 /** The exception to throw from get() */
175 private Throwable exception;
178 * The thread running task. When nulled after set/cancel, this
179 * indicates that the results are accessible. Must be
180 * volatile, to ensure visibility upon completion.
182 private volatile Thread runner;
184 Sync(Callable<V> callable) {
185 this.callable = callable;
188 private boolean ranOrCancelled(int state) {
189 return (state & (RAN | CANCELLED)) != 0;
193 * Implements AQS base acquire to succeed if ran or cancelled
195 protected int tryAcquireShared(int ignore) {
196 return innerIsDone()? 1 : -1;
200 * Implements AQS base release to always signal after setting
201 * final done status by nulling runner thread.
203 protected boolean tryReleaseShared(int ignore) {
208 boolean innerIsCancelled() {
209 return getState() == CANCELLED;
212 boolean innerIsDone() {
213 return ranOrCancelled(getState()) && runner == null;
216 V innerGet() throws InterruptedException, ExecutionException {
217 acquireSharedInterruptibly(0);
218 if (getState() == CANCELLED)
219 throw new CancellationException();
220 if (exception != null)
221 throw new ExecutionException(exception);
225 V innerGet(long nanosTimeout) throws InterruptedException, ExecutionException, TimeoutException {
226 if (!tryAcquireSharedNanos(0, nanosTimeout))
227 throw new TimeoutException();
228 if (getState() == CANCELLED)
229 throw new CancellationException();
230 if (exception != null)
231 throw new ExecutionException(exception);
240 if (s == CANCELLED) {
241 // aggressively release to set runner to null,
242 // in case we are racing with a cancel request
243 // that will try to interrupt runner
247 if (compareAndSetState(s, RAN)) {
256 void innerSetException(Throwable t) {
261 if (s == CANCELLED) {
262 // aggressively release to set runner to null,
263 // in case we are racing with a cancel request
264 // that will try to interrupt runner
268 if (compareAndSetState(s, RAN)) {
278 boolean innerCancel(boolean mayInterruptIfRunning) {
281 if (ranOrCancelled(s))
283 if (compareAndSetState(s, CANCELLED))
286 if (mayInterruptIfRunning) {
297 if (!compareAndSetState(0, RUNNING))
300 runner = Thread.currentThread();
301 if (getState() == RUNNING) // recheck after setting thread
302 innerSet(callable.call());
304 releaseShared(0); // cancel
305 } catch (Throwable ex) {
306 innerSetException(ex);
310 boolean innerRunAndReset() {
311 if (!compareAndSetState(0, RUNNING))
314 runner = Thread.currentThread();
315 if (getState() == RUNNING)
316 callable.call(); // don't set result
318 return compareAndSetState(RUNNING, 0);
319 } catch (Throwable ex) {
320 innerSetException(ex);