1/*
2 * Written by Doug Lea with assistance from members of JCP JSR-166
3 * Expert Group and released to the public domain, as explained at
4 * http://creativecommons.org/publicdomain/zero/1.0/
5 */
6
7package java.util.concurrent;
8
9/**
10 * A {@code Future} 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 * {@code get} when the computation has completed, blocking if
15 * necessary until it is ready.  Cancellation is performed by the
16 * {@code cancel} 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 * If you would like to use a {@code Future} for the sake
20 * of cancellability but not provide a usable result, you can
21 * declare types of the form {@code Future<?>} and
22 * return {@code null} as a result of the underlying task.
23 *
24 * <p>
25 * <b>Sample Usage</b> (Note that the following classes are all
26 * made-up.) <p>
27 *  <pre> {@code
28 * interface ArchiveSearcher { String search(String target); }
29 * class App {
30 *   ExecutorService executor = ...
31 *   ArchiveSearcher searcher = ...
32 *   void showSearch(final String target)
33 *       throws InterruptedException {
34 *     Future<String> future
35 *       = executor.submit(new Callable<String>() {
36 *         public String call() {
37 *             return searcher.search(target);
38 *         }});
39 *     displayOtherThings(); // do other things while searching
40 *     try {
41 *       displayText(future.get()); // use future
42 *     } catch (ExecutionException ex) { cleanup(); return; }
43 *   }
44 * }}</pre>
45 *
46 * The {@link FutureTask} class is an implementation of {@code Future} that
47 * implements {@code Runnable}, and so may be executed by an {@code Executor}.
48 * For example, the above construction with {@code submit} could be replaced by:
49 *  <pre> {@code
50 * FutureTask<String> future =
51 *   new FutureTask<String>(new Callable<String>() {
52 *     public String call() {
53 *       return searcher.search(target);
54 *   }});
55 * executor.execute(future);}</pre>
56 *
57 * <p>Memory consistency effects: Actions taken by the asynchronous computation
58 * <a href="package-summary.html#MemoryVisibility"> <i>happen-before</i></a>
59 * actions following the corresponding {@code Future.get()} in another thread.
60 *
61 * @see FutureTask
62 * @see Executor
63 * @since 1.5
64 * @author Doug Lea
65 * @param <V> The result type returned by this Future's {@code get} method
66 */
67public interface Future<V> {
68
69    /**
70     * Attempts to cancel execution of this task.  This attempt will
71     * fail if the task has already completed, has already been cancelled,
72     * or could not be cancelled for some other reason. If successful,
73     * and this task has not started when {@code cancel} is called,
74     * this task should never run.  If the task has already started,
75     * then the {@code mayInterruptIfRunning} parameter determines
76     * whether the thread executing this task should be interrupted in
77     * an attempt to stop the task.
78     *
79     * <p>After this method returns, subsequent calls to {@link #isDone} will
80     * always return {@code true}.  Subsequent calls to {@link #isCancelled}
81     * will always return {@code true} if this method returned {@code true}.
82     *
83     * @param mayInterruptIfRunning {@code true} if the thread executing this
84     * task should be interrupted; otherwise, in-progress tasks are allowed
85     * to complete
86     * @return {@code false} if the task could not be cancelled,
87     * typically because it has already completed normally;
88     * {@code true} otherwise
89     */
90    boolean cancel(boolean mayInterruptIfRunning);
91
92    /**
93     * Returns {@code true} if this task was cancelled before it completed
94     * normally.
95     *
96     * @return {@code true} if this task was cancelled before it completed
97     */
98    boolean isCancelled();
99
100    /**
101     * Returns {@code true} if this task completed.
102     *
103     * Completion may be due to normal termination, an exception, or
104     * cancellation -- in all of these cases, this method will return
105     * {@code true}.
106     *
107     * @return {@code true} if this task completed
108     */
109    boolean isDone();
110
111    /**
112     * Waits if necessary for the computation to complete, and then
113     * retrieves its result.
114     *
115     * @return the computed result
116     * @throws CancellationException if the computation was cancelled
117     * @throws ExecutionException if the computation threw an
118     * exception
119     * @throws InterruptedException if the current thread was interrupted
120     * while waiting
121     */
122    V get() throws InterruptedException, ExecutionException;
123
124    /**
125     * Waits if necessary for at most the given time for the computation
126     * to complete, and then retrieves its result, if available.
127     *
128     * @param timeout the maximum time to wait
129     * @param unit the time unit of the timeout argument
130     * @return the computed result
131     * @throws CancellationException if the computation was cancelled
132     * @throws ExecutionException if the computation threw an
133     * exception
134     * @throws InterruptedException if the current thread was interrupted
135     * while waiting
136     * @throws TimeoutException if the wait timed out
137     */
138    V get(long timeout, TimeUnit unit)
139        throws InterruptedException, ExecutionException, TimeoutException;
140}
141