util/concurrent/Future.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 <tt>Future</tt> represents the result of an asynchronous
 * computation.  Methods are provided to check if the computation is
 * complete, to wait for its completion, and to retrieve the result of
 * the computation.  The result can only be retrieved using method
 * <tt>get</tt> when the computation has completed, blocking if
 * necessary until it is ready.  Cancellation is performed by the
 * <tt>cancel</tt> method.  Additional methods are provided to
 * determine if the task completed normally or was cancelled. Once a
 * computation has completed, the computation cannot be cancelled.
 *
 * <p>
 * <b>Sample Usage</b> (Note that the following classes are all
 * made-up.) <p>
 * <pre>
 * interface ArchiveSearcher { String search(String target); }
 * class App {
 *   ExecutorService executor = ...
 *   ArchiveSearcher searcher = ...
 *   void showSearch(final String target) throws InterruptedException {
 *     Future&lt;String&gt; future = executor.submit(new Callable&lt;String&gt;() {
 *         public String call() { return searcher.search(target); }
 *     });
 *     displayOtherThings(); // do other things while searching
 *     try {
 *       displayText(future.get()); // use future
 *     } catch (ExecutionException ex) { cleanup(); return; }
 *   }
 * }
 * </pre>
 *
 * The {@link FutureTask} class is an implementation of <tt>Future</tt> that 
 * implements <tt>Runnable</tt>, and so may be executed by an <tt>Executor</tt>. 
 * For example, the above construction with <tt>submit</tt> could be replaced by:
 * <pre>
 *     FutureTask&lt;String&gt; future =
 *       new FutureTask&lt;String&gt;(new Callable&lt;String&gt;() {
 *         public String call() {
 *           return searcher.search(target);
 *       }});
 *     executor.execute(future);
 * </pre>
 * @see FutureTask
 * @see Executor
 * @since 1.5
 * @author Doug Lea
 * @param <V> The result type returned by this Future's <tt>get</tt> method
 */
public interface Future<V> {

    /**
     * Attempts to cancel execution of this task.  This attempt will
     * fail if the task has already completed, already been cancelled,
     * or could not be cancelled for some other reason. If successful,
     * and this task has not started when <tt>cancel</tt> is called,
     * this task should never run.  If the task has already started,
     * then the <tt>interruptIfRunning</tt> parameter determines
     * whether the thread executing this task should be interrupted in
     * an attempt to stop the task.
     *
     * @param mayInterruptIfRunning <tt>true</tt> if the thread executing this
     * task should be interrupted; otherwise, in-progress tasks are allowed
     * to complete
     * @return <tt>false</tt> if the task could not be cancelled,
     * typically because it has already completed normally;
     * <tt>true</tt> otherwise
     */
    boolean cancel(boolean mayInterruptIfRunning);

    /**
     * Returns <tt>true</tt> if this task was cancelled before it completed
     * normally.
     *
     * @return <tt>true</tt> if task was cancelled before it completed
     */
    boolean isCancelled();

    /**
     * Returns <tt>true</tt> if this task completed.  
     *
     * Completion may be due to normal termination, an exception, or
     * cancellation -- in all of these cases, this method will return
     * <tt>true</tt>.
     * 
     * @return <tt>true</tt> if this task completed.
     */
    boolean isDone();

    /**
     * Waits if necessary for computation to complete, and then
     * retrieves its result.
     *
     * @return computed result
     * @throws CancellationException if this future was cancelled.
     * @throws ExecutionException if underlying computation threw an
     * exception
     * @throws InterruptedException if current thread was interrupted
     * while waiting
     */
    V get() throws InterruptedException, ExecutionException;

    /**
     * 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 computed result
     * @throws ExecutionException if underlying computation threw an
     * exception
     * @throws InterruptedException if current thread was interrupted
     * while waiting
     * @throws TimeoutException if the wait timed out
     */
    V get(long timeout, TimeUnit unit)
        throws InterruptedException, ExecutionException, TimeoutException;
}


Revision:	1.19
Committed:	Mon Dec 15 08:30:09 2003 UTC (20 years, 5 months ago) by jozart
Branch:	MAIN
Changes since 1.18:	+1 -1 lines
Log Message:	Fixed typo in cancel doc.
#	User	Rev	Content
1	tim	1.1	/*
2	dl	1.12	* 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.12	* A <tt>Future</tt> represents the result of an asynchronous
11			* computation. Methods are provided to check if the computation is
12			* complete, to wait for its completion, and to retrieve the result of
13			* the computation. The result can only be retrieved using method
14			* <tt>get</tt> when the computation has completed, blocking if
15	dl	1.17	* necessary until it is ready. Cancellation is performed by the
16			* <tt>cancel</tt> method. Additional methods are provided to
17			* determine if the task completed normally or was cancelled. Once a
18			* computation has completed, the computation cannot be cancelled.
19	tim	1.1	*
20			* <p>
21	dl	1.5	* <b>Sample Usage</b> (Note that the following classes are all
22			* made-up.) <p>
23	tim	1.1	* <pre>
24	dl	1.10	* interface ArchiveSearcher { String search(String target); }
25	tim	1.1	* class App {
26	tim	1.18	* ExecutorService executor = ...
27	dl	1.5	* ArchiveSearcher searcher = ...
28			* void showSearch(final String target) throws InterruptedException {
29	tim	1.18	* Future<String> future = executor.submit(new Callable<String>() {
30			* public String call() { return searcher.search(target); }
31			* });
32	dl	1.5	* displayOtherThings(); // do other things while searching
33	tim	1.1	* try {
34	dl	1.5	* displayText(future.get()); // use future
35	tim	1.8	* } catch (ExecutionException ex) { cleanup(); return; }
36	tim	1.1	* }
37			* }
38			* </pre>
39			*
40	tim	1.18	* The {@link FutureTask} class is an implementation of <tt>Future</tt> that
41			* implements <tt>Runnable</tt>, and so may be executed by an <tt>Executor</tt>.
42			* For example, the above construction with <tt>submit</tt> could be replaced by:
43	dl	1.10	* <pre>
44	tim	1.18	* FutureTask<String> future =
45			* new FutureTask<String>(new Callable<String>() {
46			* public String call() {
47			* return searcher.search(target);
48			* }});
49			* executor.execute(future);
50	dl	1.10	* </pre>
51	tim	1.1	* @see FutureTask
52			* @see Executor
53	dl	1.12	* @since 1.5
54	dl	1.4	* @author Doug Lea
55	dl	1.16	* @param <V> The result type returned by this Future's <tt>get</tt> method
56	tim	1.1	*/
57	dl	1.17	public interface Future<V> {
58
59			/**
60			* Attempts to cancel execution of this task. This attempt will
61			* fail if the task has already completed, already been cancelled,
62			* or could not be cancelled for some other reason. If successful,
63			* and this task has not started when <tt>cancel</tt> is called,
64			* this task should never run. If the task has already started,
65			* then the <tt>interruptIfRunning</tt> parameter determines
66			* whether the thread executing this task should be interrupted in
67			* an attempt to stop the task.
68			*
69			* @param mayInterruptIfRunning <tt>true</tt> if the thread executing this
70			* task should be interrupted; otherwise, in-progress tasks are allowed
71			* to complete
72			* @return <tt>false</tt> if the task could not be cancelled,
73	jozart	1.19	* typically because it has already completed normally;
74	dl	1.17	* <tt>true</tt> otherwise
75			*/
76			boolean cancel(boolean mayInterruptIfRunning);
77
78			/**
79			* Returns <tt>true</tt> if this task was cancelled before it completed
80			* normally.
81			*
82			* @return <tt>true</tt> if task was cancelled before it completed
83			*/
84			boolean isCancelled();
85
86			/**
87			* Returns <tt>true</tt> if this task completed.
88			*
89			* Completion may be due to normal termination, an exception, or
90			* cancellation -- in all of these cases, this method will return
91			* <tt>true</tt>.
92			*
93			* @return <tt>true</tt> if this task completed.
94			*/
95			boolean isDone();
96	tim	1.1
97			/**
98			* Waits if necessary for computation to complete, and then
99			* retrieves its result.
100			*
101			* @return computed result
102	dl	1.11	* @throws CancellationException if this future was cancelled.
103	dl	1.4	* @throws ExecutionException if underlying computation threw an
104			* exception
105			* @throws InterruptedException if current thread was interrupted
106			* while waiting
107	tim	1.1	*/
108			V get() throws InterruptedException, ExecutionException;
109
110			/**
111			* Waits if necessary for at most the given time for the computation
112			* to complete, and then retrieves its result.
113			*
114			* @param timeout the maximum time to wait
115	dl	1.14	* @param unit the time unit of the timeout argument
116	tim	1.1	* @return computed result
117	dl	1.4	* @throws ExecutionException if underlying computation threw an
118			* exception
119			* @throws InterruptedException if current thread was interrupted
120			* while waiting
121	tim	1.1	* @throws TimeoutException if the wait timed out
122			*/
123	dl	1.14	V get(long timeout, TimeUnit unit)
124	tim	1.1	throws InterruptedException, ExecutionException, TimeoutException;
125			}
126
127
128