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, 9 months ago) by dl
Branch:	MAIN
Changes since 1.8:	+7 -1 lines
Log Message:	Adapt AbstractQueue changes; Conditionalize CancellableTask.reset; new TimeUnit methods
#	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. 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	* 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	* the computation has completed, the computation cannot be restarted
17	* or cancelled.
18	*
19	* <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	*
24	* @since 1.5
25	* @author Doug Lea
26	*/
27	public class FutureTask<V> extends CancellableTask implements Future<V> {
28
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	* @throws NullPointerException if callable is null
35	*/
36	public FutureTask(Callable<V> callable) {
37	// must set after super ctor call to use inner class
38	super();
39	if (callable == null)
40	throw new NullPointerException();
41	setRunnable(new InnerCancellableFuture<V>(callable));
42	}
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	* you don't need a particular result, consider using
52	* <tt>Boolean.TRUE</tt>.
53	* @throws NullPointerException if runnable is null
54	*/
55	public FutureTask(final Runnable runnable, final V result) {
56	super();
57	if (runnable == null)
58	throw new NullPointerException();
59	setRunnable(new InnerCancellableFuture<V>
60	(new Callable<V>() {
61	public V call() {
62	runnable.run();
63	return result;
64	}
65	}));
66	}
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	* @throws ExecutionException if the underlying computation threw
76	* an exception
77	* @throws InterruptedException if current thread was interrupted
78	* while waiting
79	*/
80	public V get() throws InterruptedException, ExecutionException {
81	return ((InnerCancellableFuture<V>)getRunnable()).get();
82	}
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	* @param unit the time unit of the timeout argument
90	* @return value of this task
91	* @throws CancellationException if task producing this value was
92	* 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	* @throws TimeoutException if the wait timed out
98	*/
99	public V get(long timeout, TimeUnit unit)
100	throws InterruptedException, ExecutionException, TimeoutException {
101	return ((InnerCancellableFuture<V>)getRunnable()).get(timeout, unit);
102	}
103
104	/**
105	* 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	*
112	* @param v the value
113	*
114	*/
115	protected void set(V v) {
116	((InnerCancellableFuture<V>)getRunnable()).set(v);
117	}
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	protected void setException(Throwable t) {
128	((InnerCancellableFuture<V>)getRunnable()).setException(t);
129	}
130
131	}
132
133
134
135
136
137
138
139
140
141