util/concurrent/FutureTask.java

/*
 * @(#)FutureTask.java
 */

package java.util.concurrent;

/**
 * A cancellable asynchronous computation.
 *
 * <p>Provides methods to start and cancel the computation, query to see if
 * the computation is complete, and retrieve the result of the computation.
 * The result can only be retrieved when the computation has completed;
 * the <tt>get</tt> method will block if the computation has not yet completed.
 * Once the computation is completed, the result cannot be changed, nor can the
 * computation be restarted or cancelled.
 *
 * <p>Because <tt>FutureTask</tt> implements <tt>Runnable</tt>, a
 * <tt>FutureTask</tt> can be submitted to an {@link Executor} for 
 * current or deferred execution.
 *
 * <p>A <tt>FutureTask</tt> can be used to wrap a <tt>Callable</tt> or 
 * <tt>Runnable</tt> object so that it can be scheduled for execution in a 
 * thread or an <tt>Executor</tt>, cancel
 * computation before the computation completes, and wait for or
 * retrieve the results.  If the computation threw an exception, the
 * exception is propagated to any thread that attempts to retrieve the
 * result.
 *
 * @see Executor
 *
 * @since 1.5
 * @spec JSR-166
 * @revised $Date: 2003/03/31 03:50:08 $
 * @editor $Author: dholmes $
 */
public class FutureTask<V> implements Cancellable, Future<V>, Runnable {

    private V result;
    private Throwable exception;
    private boolean ready;
    private Thread runner;
    private final Callable<V> callable;
    private boolean cancelled;

    /**
     * Constructs a <tt>FutureTask</tt> that will upon running, execute the
     * given <tt>Callable</tt>.
     *
     * @param  callable the callable task
     */
    public FutureTask(Callable<V> callable) {
        this.callable = callable;
    }

    /**
     * Constructs a <tt>FutureTask</tt> that will upon running, execute the
     * given <tt>Runnable</tt>, and arrange that <tt>get</tt> will return the
     * given result on successful completion.
     *
     * @param  runnable the runnable task
     * @param result the result to return on successful completion. If
     * you don't need a particular result, consider just using
     * <tt>Boolean.TRUE</tt>.
     */
    public FutureTask(final Runnable runnable, final V result) {
        callable = new Callable<V>() {
            public V call() {
                runnable.run();
                return result;
            }
        };
    }

    /* Runnable implementation. */

    /** Starts the computation. */
    public void run() {
        doRun();
    }

    /**
     * Executes the callable if not already cancelled or running, and
     * sets the value or exception with its results.
     */
    protected void doRun() {
        try {
            synchronized(this) {
                if (ready || runner != null)
                    return;
                runner = Thread.currentThread();
            }
            set(callable.call());
        }
        catch(Throwable ex) {
            setException(ex);
        }
    }

    /* Future implementation. INHERIT this javadoc from interface??? Note CancellationException. */

    /**
     * Waits if necessary for the computation to complete, and then retrieves
     * its result.
     *
     * @return the computed result
     * @throws CancellationException if task producing this value was
     * cancelled before completion
     * @throws ExecutionException if the underlying computation threw an exception
     * @throws InterruptedException if current thread was interrupted while waiting
     */
    public synchronized V get() throws InterruptedException, ExecutionException {
        while (!ready)
            wait();
        if (cancelled)
            throw new CancellationException();
        else if (exception != null)
            throw new ExecutionException(exception);
        else
            return result;
    }

    /**
     * Waits if necessary for at most the given time for the computation to
     * complete, and then retrieves its result.
     *
     * @param timeout the maximum time to wait
     * @param granularity the time unit of the timeout argument
     * @return value of this task
     * @throws CancellationException if task producing this value was cancelled before completion
     * @throws ExecutionException if the underlying computation
     * threw an exception.
     * @throws InterruptedException if current thread was interrupted while waiting
     * @throws TimeoutException if the wait timed out
     */
    public synchronized V get(long timeout, TimeUnit granularity)
        throws InterruptedException, ExecutionException, TimeoutException {

        if (!ready) {
            long startTime = TimeUnit.highResolutionTime();
            long waitTime = timeout;
            for (;;) {
                granularity.timedWait(this, waitTime);
                if (ready)
                    break;
                else {
                    waitTime = TimeUnit.highResolutionTime() - startTime;
                    if (waitTime <= 0)
                        throw new TimeoutException();
                }
            }
        }
        if (cancelled)
            throw new CancellationException();
        else if (exception != null)
            throw new ExecutionException(exception);
        else
            return result;
    }

    /**
     * Sets the value of this task to the given value.  This method
     * should only be called once; once it is called, the computation
     * is assumed to have completed.
     *
     * @param v the value
     *
     * @fixme Need to clarify "should" in "should only be called once".
     */
    protected synchronized void set(V v) {
        ready = true;
        result = v;
        runner = null;
        notifyAll();
    }

    /**
     * Indicates that the computation has failed.  After this method
     * is called, the computation is assumed to be completed, and any
     * attempt to retrieve the result will throw an <tt>ExecutionException</tt>
     * wrapping the exception provided here.
     *
     * @param t the throwable
     */
    protected synchronized void setException(Throwable t) {
        ready = true;
        exception = t;
        runner = null;
        notifyAll();
    }

    /* Cancellable implementation. */

    public synchronized boolean cancel(boolean mayInterruptIfRunning) {
        if (ready || cancelled)
            return false;
        if (mayInterruptIfRunning &&
            runner != null && runner != Thread.currentThread())
            runner.interrupt();
        return cancelled = ready = true;
    }

    public synchronized boolean isCancelled() {
        return cancelled;
    }

    public synchronized boolean isDone() {
        return ready;
    }
}


Revision:	1.1
Committed:	Wed May 14 21:30:47 2003 UTC (21 years, 1 month ago) by tim
Branch:	MAIN
Log Message:	Moved main source rooted at . to ./src/main Moved test source rooted at ./etc/testcases to ./src/test
#	Content
1	/*
2	* @(#)FutureTask.java
3	*/
4
5	package java.util.concurrent;
6
7	/**
8	* A cancellable asynchronous computation.
9	*
10	* <p>Provides methods to start and cancel the computation, query to see if
11	* the computation is complete, and retrieve the result of the computation.
12	* The result can only be retrieved when the computation has completed;
13	* the <tt>get</tt> method will block if the computation has not yet completed.
14	* Once the computation is completed, the result cannot be changed, nor can the
15	* computation be restarted or cancelled.
16	*
17	* <p>Because <tt>FutureTask</tt> implements <tt>Runnable</tt>, a
18	* <tt>FutureTask</tt> can be submitted to an {@link Executor} for
19	* current or deferred execution.
20	*
21	* <p>A <tt>FutureTask</tt> can be used to wrap a <tt>Callable</tt> or
22	* <tt>Runnable</tt> object so that it can be scheduled for execution in a
23	* thread or an <tt>Executor</tt>, cancel
24	* computation before the computation completes, and wait for or
25	* retrieve the results. If the computation threw an exception, the
26	* exception is propagated to any thread that attempts to retrieve the
27	* result.
28	*
29	* @see Executor
30	*
31	* @since 1.5
32	* @spec JSR-166
33	* @revised $Date: 2003/03/31 03:50:08 $
34	* @editor $Author: dholmes $
35	*/
36	public class FutureTask<V> implements Cancellable, Future<V>, Runnable {
37
38	private V result;
39	private Throwable exception;
40	private boolean ready;
41	private Thread runner;
42	private final Callable<V> callable;
43	private boolean cancelled;
44
45	/**
46	* Constructs a <tt>FutureTask</tt> that will upon running, execute the
47	* given <tt>Callable</tt>.
48	*
49	* @param callable the callable task
50	*/
51	public FutureTask(Callable<V> callable) {
52	this.callable = callable;
53	}
54
55	/**
56	* Constructs a <tt>FutureTask</tt> that will upon running, execute the
57	* given <tt>Runnable</tt>, and arrange that <tt>get</tt> will return the
58	* given result on successful completion.
59	*
60	* @param runnable the runnable task
61	* @param result the result to return on successful completion. If
62	* you don't need a particular result, consider just using
63	* <tt>Boolean.TRUE</tt>.
64	*/
65	public FutureTask(final Runnable runnable, final V result) {
66	callable = new Callable<V>() {
67	public V call() {
68	runnable.run();
69	return result;
70	}
71	};
72	}
73
74	/* Runnable implementation. */
75
76	/** Starts the computation. */
77	public void run() {
78	doRun();
79	}
80
81	/**
82	* Executes the callable if not already cancelled or running, and
83	* sets the value or exception with its results.
84	*/
85	protected void doRun() {
86	try {
87	synchronized(this) {
88	if (ready \|\| runner != null)
89	return;
90	runner = Thread.currentThread();
91	}
92	set(callable.call());
93	}
94	catch(Throwable ex) {
95	setException(ex);
96	}
97	}
98
99	/* Future implementation. INHERIT this javadoc from interface??? Note CancellationException. */
100
101	/**
102	* Waits if necessary for the computation to complete, and then retrieves
103	* its result.
104	*
105	* @return the computed result
106	* @throws CancellationException if task producing this value was
107	* cancelled before completion
108	* @throws ExecutionException if the underlying computation threw an exception
109	* @throws InterruptedException if current thread was interrupted while waiting
110	*/
111	public synchronized V get() throws InterruptedException, ExecutionException {
112	while (!ready)
113	wait();
114	if (cancelled)
115	throw new CancellationException();
116	else if (exception != null)
117	throw new ExecutionException(exception);
118	else
119	return result;
120	}
121
122	/**
123	* Waits if necessary for at most the given time for the computation to
124	* complete, and then retrieves its result.
125	*
126	* @param timeout the maximum time to wait
127	* @param granularity the time unit of the timeout argument
128	* @return value of this task
129	* @throws CancellationException if task producing this value was cancelled before completion
130	* @throws ExecutionException if the underlying computation
131	* threw an exception.
132	* @throws InterruptedException if current thread was interrupted while waiting
133	* @throws TimeoutException if the wait timed out
134	*/
135	public synchronized V get(long timeout, TimeUnit granularity)
136	throws InterruptedException, ExecutionException, TimeoutException {
137
138	if (!ready) {
139	long startTime = TimeUnit.highResolutionTime();
140	long waitTime = timeout;
141	for (;;) {
142	granularity.timedWait(this, waitTime);
143	if (ready)
144	break;
145	else {
146	waitTime = TimeUnit.highResolutionTime() - startTime;
147	if (waitTime <= 0)
148	throw new TimeoutException();
149	}
150	}
151	}
152	if (cancelled)
153	throw new CancellationException();
154	else if (exception != null)
155	throw new ExecutionException(exception);
156	else
157	return result;
158	}
159
160	/**
161	* Sets the value of this task to the given value. This method
162	* should only be called once; once it is called, the computation
163	* is assumed to have completed.
164	*
165	* @param v the value
166	*
167	* @fixme Need to clarify "should" in "should only be called once".
168	*/
169	protected synchronized void set(V v) {
170	ready = true;
171	result = v;
172	runner = null;
173	notifyAll();
174	}
175
176	/**
177	* Indicates that the computation has failed. After this method
178	* is called, the computation is assumed to be completed, and any
179	* attempt to retrieve the result will throw an <tt>ExecutionException</tt>
180	* wrapping the exception provided here.
181	*
182	* @param t the throwable
183	*/
184	protected synchronized void setException(Throwable t) {
185	ready = true;
186	exception = t;
187	runner = null;
188	notifyAll();
189	}
190
191	/* Cancellable implementation. */
192
193	public synchronized boolean cancel(boolean mayInterruptIfRunning) {
194	if (ready \|\| cancelled)
195	return false;
196	if (mayInterruptIfRunning &&
197	runner != null && runner != Thread.currentThread())
198	runner.interrupt();
199	return cancelled = ready = true;
200	}
201
202	public synchronized boolean isCancelled() {
203	return cancelled;
204	}
205
206	public synchronized boolean isDone() {
207	return ready;
208	}
209	}
210
211
212
213
214
215
216
217
218
219