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
 * @param <V> The result type returned by this FutureTask's <tt>get</tt> method
 */
public class FutureTask<V> extends CancellableTask implements Future<V> {

    /** 
     * Callable created in FutureTask(runnable, result) constructor
     */
    private static class RunnableAsCallable<V> implements Callable<V> {
        private final Runnable runnable;
        private final V result;
        RunnableAsCallable(Runnable runnable, V result) {
            this.runnable = runnable;
            this.result = result;
        }
        public V call() {
            runnable.run();
            return result;
        }
    }

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