util/concurrent/FutureTask.java

/*
 * Written by Doug Lea with assistance from members of JCP JSR-166
 * Expert Group and released to the public domain. Use, modify, and
 * redistribute this code in any way without acknowledgement.
 */

package java.util.concurrent;

/**
 * A cancellable asynchronous computation.
 *
 * <p><tt>FutureTask</tt> 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/06/03 16:44:36 $
 * @editor $Author: dl $
 * @author Doug Lea
 */
public class FutureTask<V> extends CancellableTask implements Cancellable, Future<V>, Runnable {

    /**
     * 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) {
        // must set after super ctor call to use inner class
        super();
        setRunnable(new InnerCancellableFuture(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) {
        super();
        setRunnable(new InnerCancellableFuture
                    (new Callable<V>() {
                        public V call() {
                            runnable.run();
                            return result;
                        }
                    }));
    }

    /**
     * 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 V get() throws InterruptedException, ExecutionException {
        return ((InnerCancellableFuture<V>)getRunnable()).get();
    }

    /**
     * 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 unit 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 V get(long timeout, TimeUnit unit)
        throws InterruptedException, ExecutionException, TimeoutException {
        return ((InnerCancellableFuture<V>)getRunnable()).get(timeout, unit);
    }

    /**
     * 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 void set(V v) {
        ((InnerCancellableFuture<V>)getRunnable()).set(v);
    }

    /**
     * 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 void setException(Throwable t) {
        ((InnerCancellableFuture<V>)getRunnable()).setException(t);
    }

}


Revision:	1.4
Committed:	Tue Jun 24 14:34:48 2003 UTC (20 years, 11 months ago) by dl
Branch:	MAIN
Changes since 1.3:	+19 -13 lines
Log Message:	Added missing javadoc tags; minor reformatting
#	User	Rev	Content
1	tim	1.1	/*
2	dl	1.2	* Written by Doug Lea with assistance from members of JCP JSR-166
3			* Expert Group and released to the public domain. Use, modify, and
4			* redistribute this code in any way without acknowledgement.
5	tim	1.1	*/
6
7			package java.util.concurrent;
8
9			/**
10			* A cancellable asynchronous computation.
11			*
12	dl	1.4	* <p><tt>FutureTask</tt> provides methods to start and cancel the
13			* 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 is completed, the result cannot be changed, nor can
18			* the computation be restarted or cancelled.
19	tim	1.1	*
20			* <p>Because <tt>FutureTask</tt> implements <tt>Runnable</tt>, a
21			* <tt>FutureTask</tt> can be submitted to an {@link Executor} for
22			* current or deferred execution.
23			*
24			* <p>A <tt>FutureTask</tt> can be used to wrap a <tt>Callable</tt> or
25			* <tt>Runnable</tt> object so that it can be scheduled for execution in a
26			* thread or an <tt>Executor</tt>, cancel
27			* computation before the computation completes, and wait for or
28			* retrieve the results. If the computation threw an exception, the
29			* exception is propagated to any thread that attempts to retrieve the
30			* result.
31			*
32			* @see Executor
33			*
34			* @since 1.5
35			* @spec JSR-166
36	dl	1.4	* @revised $Date: 2003/06/03 16:44:36 $
37	dl	1.3	* @editor $Author: dl $
38	dl	1.4	* @author Doug Lea
39	tim	1.1	*/
40	dl	1.3	public class FutureTask<V> extends CancellableTask implements Cancellable, Future<V>, Runnable {
41	tim	1.1
42			/**
43			* Constructs a <tt>FutureTask</tt> that will upon running, execute the
44			* given <tt>Callable</tt>.
45			*
46			* @param callable the callable task
47			*/
48			public FutureTask(Callable<V> callable) {
49	dl	1.3	// must set after super ctor call to use inner class
50			super();
51			setRunnable(new InnerCancellableFuture(callable));
52	tim	1.1	}
53
54			/**
55			* Constructs a <tt>FutureTask</tt> that will upon running, execute the
56			* given <tt>Runnable</tt>, and arrange that <tt>get</tt> will return the
57			* given result on successful completion.
58			*
59			* @param runnable the runnable task
60			* @param result the result to return on successful completion. If
61			* you don't need a particular result, consider just using
62			* <tt>Boolean.TRUE</tt>.
63			*/
64			public FutureTask(final Runnable runnable, final V result) {
65	dl	1.3	super();
66			setRunnable(new InnerCancellableFuture
67			(new Callable<V>() {
68			public V call() {
69			runnable.run();
70			return result;
71			}
72			}));
73	tim	1.1	}
74
75			/**
76			* Waits if necessary for the computation to complete, and then retrieves
77			* its result.
78			*
79			* @return the computed result
80			* @throws CancellationException if task producing this value was
81			* cancelled before completion
82	dl	1.4	* @throws ExecutionException if the underlying computation threw
83			* an exception
84			* @throws InterruptedException if current thread was interrupted
85			* while waiting
86	tim	1.1	*/
87	dl	1.2	public V get() throws InterruptedException, ExecutionException {
88	dl	1.3	return ((InnerCancellableFuture<V>)getRunnable()).get();
89	tim	1.1	}
90
91			/**
92			* Waits if necessary for at most the given time for the computation to
93			* complete, and then retrieves its result.
94			*
95			* @param timeout the maximum time to wait
96	dl	1.2	* @param unit the time unit of the timeout argument
97	tim	1.1	* @return value of this task
98	dl	1.4	* @throws CancellationException if task producing this value was
99			* cancelled before completion
100			* @throws ExecutionException if the underlying computation threw
101			* an exception.
102			* @throws InterruptedException if current thread was interrupted
103			* while waiting
104	tim	1.1	* @throws TimeoutException if the wait timed out
105			*/
106	dl	1.2	public V get(long timeout, TimeUnit unit)
107	tim	1.1	throws InterruptedException, ExecutionException, TimeoutException {
108	dl	1.3	return ((InnerCancellableFuture<V>)getRunnable()).get(timeout, unit);
109	tim	1.1	}
110
111			/**
112			* Sets the value of this task to the given value. This method
113			* should only be called once; once it is called, the computation
114			* is assumed to have completed.
115			*
116			* @param v the value
117			*
118			* @fixme Need to clarify "should" in "should only be called once".
119			*/
120	dl	1.2	protected void set(V v) {
121	dl	1.3	((InnerCancellableFuture<V>)getRunnable()).set(v);
122	tim	1.1	}
123
124			/**
125			* Indicates that the computation has failed. After this method
126			* is called, the computation is assumed to be completed, and any
127			* attempt to retrieve the result will throw an <tt>ExecutionException</tt>
128			* wrapping the exception provided here.
129			*
130			* @param t the throwable
131			*/
132	dl	1.2	protected void setException(Throwable t) {
133	dl	1.3	((InnerCancellableFuture<V>)getRunnable()).setException(t);
134	tim	1.1	}
135	dl	1.3
136	tim	1.1	}
137
138
139
140
141
142
143
144
145
146