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.  This class provides a base
 * implementation of {@link Future}, with methods to start and cancel
 * a 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 has completed, the computation cannot be restarted
 * or cancelled.
 *
 * <p>A <tt>FutureTask</tt> can be used to wrap a {@link Callable} or
 * {@link java.lang.Runnable} object.  Because <tt>FutureTask</tt>
 * implements <tt>Runnable</tt>, a <tt>FutureTask</tt> can be
 * submitted to an {@link Executor} for execution.
 *
 * @since 1.5
 * @author Doug Lea
 */
public class FutureTask<V> extends CancellableTask implements Future<V> {

    /**
     * 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<V>(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<V>
                    (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.  After this
     * method is called, the computation is assumed to be completed --
     * threads already waiting for the result via <tt>get</tt> are
     * unblocked, and future attempts to retrieve the result will not
     * block. While not explicity disallowed, it is rarely a good idea
     * to invoke <tt>set</tt> more than once.
     *
     * @param v the value
     *
     */
    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.8
Committed:	Sun Aug 31 13:33:13 2003 UTC (20 years, 9 months ago) by dl
Branch:	MAIN
Changes since 1.7:	+9 -22 lines
Log Message:	Removed non-standard tags and misc javadoc cleanup
#	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	dl	1.8	* A cancellable asynchronous computation. This class provides a base
11			* implementation of {@link Future}, with methods to start and cancel
12			* a computation, query to see if the computation is complete, and
13	dl	1.4	* retrieve the result of the computation. The result can only be
14			* retrieved when the computation has completed; the <tt>get</tt>
15			* method will block if the computation has not yet completed. Once
16	dl	1.8	* the computation has completed, the computation cannot be restarted
17			* or cancelled.
18	tim	1.1	*
19	dl	1.8	* <p>A <tt>FutureTask</tt> can be used to wrap a {@link Callable} or
20			* {@link java.lang.Runnable} object. Because <tt>FutureTask</tt>
21			* implements <tt>Runnable</tt>, a <tt>FutureTask</tt> can be
22			* submitted to an {@link Executor} for execution.
23	tim	1.1	*
24			* @since 1.5
25	dl	1.4	* @author Doug Lea
26	tim	1.1	*/
27	jozart	1.5	public class FutureTask<V> extends CancellableTask implements Future<V> {
28	tim	1.1
29			/**
30			* Constructs a <tt>FutureTask</tt> that will upon running, execute the
31			* given <tt>Callable</tt>.
32			*
33			* @param callable the callable task
34			*/
35			public FutureTask(Callable<V> callable) {
36	dl	1.3	// must set after super ctor call to use inner class
37			super();
38	tim	1.6	setRunnable(new InnerCancellableFuture<V>(callable));
39	tim	1.1	}
40
41			/**
42			* Constructs a <tt>FutureTask</tt> that will upon running, execute the
43			* given <tt>Runnable</tt>, and arrange that <tt>get</tt> will return the
44			* given result on successful completion.
45			*
46			* @param runnable the runnable task
47			* @param result the result to return on successful completion. If
48			* you don't need a particular result, consider just using
49			* <tt>Boolean.TRUE</tt>.
50			*/
51			public FutureTask(final Runnable runnable, final V result) {
52	dl	1.3	super();
53	tim	1.6	setRunnable(new InnerCancellableFuture<V>
54	dl	1.3	(new Callable<V>() {
55			public V call() {
56			runnable.run();
57			return result;
58			}
59			}));
60	tim	1.1	}
61
62			/**
63			* Waits if necessary for the computation to complete, and then retrieves
64			* its result.
65			*
66			* @return the computed result
67			* @throws CancellationException if task producing this value was
68			* cancelled before completion
69	dl	1.4	* @throws ExecutionException if the underlying computation threw
70			* an exception
71			* @throws InterruptedException if current thread was interrupted
72			* while waiting
73	tim	1.1	*/
74	dl	1.2	public V get() throws InterruptedException, ExecutionException {
75	dl	1.3	return ((InnerCancellableFuture<V>)getRunnable()).get();
76	tim	1.1	}
77
78			/**
79			* Waits if necessary for at most the given time for the computation to
80			* complete, and then retrieves its result.
81			*
82			* @param timeout the maximum time to wait
83	dl	1.2	* @param unit the time unit of the timeout argument
84	tim	1.1	* @return value of this task
85	tim	1.6	* @throws CancellationException if task producing this value was
86	dl	1.4	* cancelled before completion
87			* @throws ExecutionException if the underlying computation threw
88			* an exception.
89			* @throws InterruptedException if current thread was interrupted
90			* while waiting
91	tim	1.1	* @throws TimeoutException if the wait timed out
92			*/
93	dl	1.2	public V get(long timeout, TimeUnit unit)
94	tim	1.1	throws InterruptedException, ExecutionException, TimeoutException {
95	dl	1.3	return ((InnerCancellableFuture<V>)getRunnable()).get(timeout, unit);
96	tim	1.1	}
97
98			/**
99	dl	1.7	* Sets the value of this task to the given value. After this
100			* method is called, the computation is assumed to be completed --
101			* threads already waiting for the result via <tt>get</tt> are
102			* unblocked, and future attempts to retrieve the result will not
103			* block. While not explicity disallowed, it is rarely a good idea
104			* to invoke <tt>set</tt> more than once.
105	tim	1.1	*
106			* @param v the value
107			*
108			*/
109	dl	1.2	protected void set(V v) {
110	dl	1.3	((InnerCancellableFuture<V>)getRunnable()).set(v);
111	tim	1.1	}
112
113			/**
114			* Indicates that the computation has failed. After this method
115			* is called, the computation is assumed to be completed, and any
116			* attempt to retrieve the result will throw an <tt>ExecutionException</tt>
117			* wrapping the exception provided here.
118			*
119			* @param t the throwable
120			*/
121	dl	1.2	protected void setException(Throwable t) {
122	dl	1.3	((InnerCancellableFuture<V>)getRunnable()).setException(t);
123	tim	1.1	}
124	dl	1.3
125	tim	1.1	}
126
127
128
129
130
131
132
133
134
135