ViewVC Help
View File | Revision Log | Show Annotations | Download File | Root Listing
root/jsr166/jsr166/src/main/java/util/concurrent/Future.java
Revision: 1.21
Committed: Fri Dec 19 14:42:25 2003 UTC (20 years, 5 months ago) by dl
Branch: MAIN
Changes since 1.20: +4 -0 lines
Log Message: 
Documentation improvements

File Contents

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