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
     * @throws NullPointerException if callable is null
     */
    public FutureTask(Callable<V> callable) {
        // must set after super ctor call to use inner class
        super();
        if (callable == null)
            throw new NullPointerException();
        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 using
     * <tt>Boolean.TRUE</tt>.
     * @throws NullPointerException if runnable is null
     */
    public FutureTask(final Runnable runnable, final V result) {
        super();
        if (runnable == null)
            throw new NullPointerException();
        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.9
Committed:	Fri Sep 12 15:40:10 2003 UTC (20 years, 8 months ago) by dl
Branch:	MAIN
Changes since 1.8:	+7 -1 lines
Log Message:	Adapt AbstractQueue changes; Conditionalize CancellableTask.reset; new TimeUnit methods
#	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	dl	1.9	* @throws NullPointerException if callable is null
35	tim	1.1	*/
36			public FutureTask(Callable<V> callable) {
37	dl	1.3	// must set after super ctor call to use inner class
38			super();
39	dl	1.9	if (callable == null)
40			throw new NullPointerException();
41	tim	1.6	setRunnable(new InnerCancellableFuture<V>(callable));
42	tim	1.1	}
43
44			/**
45			* Constructs a <tt>FutureTask</tt> that will upon running, execute the
46			* given <tt>Runnable</tt>, and arrange that <tt>get</tt> will return the
47			* given result on successful completion.
48			*
49			* @param runnable the runnable task
50			* @param result the result to return on successful completion. If
51	dl	1.9	* you don't need a particular result, consider using
52	tim	1.1	* <tt>Boolean.TRUE</tt>.
53	dl	1.9	* @throws NullPointerException if runnable is null
54	tim	1.1	*/
55			public FutureTask(final Runnable runnable, final V result) {
56	dl	1.3	super();
57	dl	1.9	if (runnable == null)
58			throw new NullPointerException();
59	tim	1.6	setRunnable(new InnerCancellableFuture<V>
60	dl	1.3	(new Callable<V>() {
61			public V call() {
62			runnable.run();
63			return result;
64			}
65			}));
66	tim	1.1	}
67
68			/**
69			* Waits if necessary for the computation to complete, and then retrieves
70			* its result.
71			*
72			* @return the computed result
73			* @throws CancellationException if task producing this value was
74			* cancelled before completion
75	dl	1.4	* @throws ExecutionException if the underlying computation threw
76			* an exception
77			* @throws InterruptedException if current thread was interrupted
78			* while waiting
79	tim	1.1	*/
80	dl	1.2	public V get() throws InterruptedException, ExecutionException {
81	dl	1.3	return ((InnerCancellableFuture<V>)getRunnable()).get();
82	tim	1.1	}
83
84			/**
85			* Waits if necessary for at most the given time for the computation to
86			* complete, and then retrieves its result.
87			*
88			* @param timeout the maximum time to wait
89	dl	1.2	* @param unit the time unit of the timeout argument
90	tim	1.1	* @return value of this task
91	tim	1.6	* @throws CancellationException if task producing this value was
92	dl	1.4	* cancelled before completion
93			* @throws ExecutionException if the underlying computation threw
94			* an exception.
95			* @throws InterruptedException if current thread was interrupted
96			* while waiting
97	tim	1.1	* @throws TimeoutException if the wait timed out
98			*/
99	dl	1.2	public V get(long timeout, TimeUnit unit)
100	tim	1.1	throws InterruptedException, ExecutionException, TimeoutException {
101	dl	1.3	return ((InnerCancellableFuture<V>)getRunnable()).get(timeout, unit);
102	tim	1.1	}
103
104			/**
105	dl	1.7	* Sets the value of this task to the given value. After this
106			* method is called, the computation is assumed to be completed --
107			* threads already waiting for the result via <tt>get</tt> are
108			* unblocked, and future attempts to retrieve the result will not
109			* block. While not explicity disallowed, it is rarely a good idea
110			* to invoke <tt>set</tt> more than once.
111	tim	1.1	*
112			* @param v the value
113			*
114			*/
115	dl	1.2	protected void set(V v) {
116	dl	1.3	((InnerCancellableFuture<V>)getRunnable()).set(v);
117	tim	1.1	}
118
119			/**
120			* Indicates that the computation has failed. After this method
121			* is called, the computation is assumed to be completed, and any
122			* attempt to retrieve the result will throw an <tt>ExecutionException</tt>
123			* wrapping the exception provided here.
124			*
125			* @param t the throwable
126			*/
127	dl	1.2	protected void setException(Throwable t) {
128	dl	1.3	((InnerCancellableFuture<V>)getRunnable()).setException(t);
129	tim	1.1	}
130	dl	1.3
131	tim	1.1	}
132
133
134
135
136
137
138
139
140
141