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