Future.java revision 29957558cf0db700bfaae360a80c42dc3871d0e5 
1/*
2 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
3 *
4 * This code is free software; you can redistribute it and/or modify it
5 * under the terms of the GNU General Public License version 2 only, as
6 * published by the Free Software Foundation.  Oracle designates this
7 * particular file as subject to the "Classpath" exception as provided
8 * by Oracle in the LICENSE file that accompanied this code.
9 *
10 * This code is distributed in the hope that it will be useful, but WITHOUT
11 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
13 * version 2 for more details (a copy is included in the LICENSE file that
14 * accompanied this code).
15 *
16 * You should have received a copy of the GNU General Public License version
17 * 2 along with this work; if not, write to the Free Software Foundation,
18 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
19 *
20 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
21 * or visit www.oracle.com if you need additional information or have any
22 * questions.
23 */
24
25/*
26 * This file is available under and governed by the GNU General Public
27 * License version 2 only, as published by the Free Software Foundation.
28 * However, the following notice accompanied the original version of this
29 * file:
30 *
31 * Written by Doug Lea with assistance from members of JCP JSR-166
32 * Expert Group and released to the public domain, as explained at
33 * http://creativecommons.org/publicdomain/zero/1.0/
34 */
35
36package java.util.concurrent;
37
38/**
39 * A {@code Future} represents the result of an asynchronous
40 * computation.  Methods are provided to check if the computation is
41 * complete, to wait for its completion, and to retrieve the result of
42 * the computation.  The result can only be retrieved using method
43 * {@code get} when the computation has completed, blocking if
44 * necessary until it is ready.  Cancellation is performed by the
45 * {@code cancel} method.  Additional methods are provided to
46 * determine if the task completed normally or was cancelled. Once a
47 * computation has completed, the computation cannot be cancelled.
48 * If you would like to use a {@code Future} for the sake
49 * of cancellability but not provide a usable result, you can
50 * declare types of the form {@code Future<?>} and
51 * return {@code null} as a result of the underlying task.
52 *
53 * <p>
54 * <b>Sample Usage</b> (Note that the following classes are all
55 * made-up.)
56 *
57 * <pre> {@code
58 * interface ArchiveSearcher { String search(String target); }
59 * class App {
60 *   ExecutorService executor = ...
61 *   ArchiveSearcher searcher = ...
62 *   void showSearch(final String target)
63 *       throws InterruptedException {
64 *     Future<String> future
65 *       = executor.submit(new Callable<String>() {
66 *         public String call() {
67 *             return searcher.search(target);
68 *         }});
69 *     displayOtherThings(); // do other things while searching
70 *     try {
71 *       displayText(future.get()); // use future
72 *     } catch (ExecutionException ex) { cleanup(); return; }
73 *   }
74 * }}</pre>
75 *
76 * The {@link FutureTask} class is an implementation of {@code Future} that
77 * implements {@code Runnable}, and so may be executed by an {@code Executor}.
78 * For example, the above construction with {@code submit} could be replaced by:
79 * <pre> {@code
80 * FutureTask<String> future =
81 *   new FutureTask<>(new Callable<String>() {
82 *     public String call() {
83 *       return searcher.search(target);
84 *   }});
85 * executor.execute(future);}</pre>
86 *
87 * <p>Memory consistency effects: Actions taken by the asynchronous computation
88 * <a href="package-summary.html#MemoryVisibility"> <i>happen-before</i></a>
89 * actions following the corresponding {@code Future.get()} in another thread.
90 *
91 * @see FutureTask
92 * @see Executor
93 * @since 1.5
94 * @author Doug Lea
95 * @param <V> The result type returned by this Future's {@code get} method
96 */
97public interface Future<V> {
98
99    /**
100     * Attempts to cancel execution of this task.  This attempt will
101     * fail if the task has already completed, has already been cancelled,
102     * or could not be cancelled for some other reason. If successful,
103     * and this task has not started when {@code cancel} is called,
104     * this task should never run.  If the task has already started,
105     * then the {@code mayInterruptIfRunning} parameter determines
106     * whether the thread executing this task should be interrupted in
107     * an attempt to stop the task.
108     *
109     * <p>After this method returns, subsequent calls to {@link #isDone} will
110     * always return {@code true}.  Subsequent calls to {@link #isCancelled}
111     * will always return {@code true} if this method returned {@code true}.
112     *
113     * @param mayInterruptIfRunning {@code true} if the thread executing this
114     * task should be interrupted; otherwise, in-progress tasks are allowed
115     * to complete
116     * @return {@code false} if the task could not be cancelled,
117     * typically because it has already completed normally;
118     * {@code true} otherwise
119     */
120    boolean cancel(boolean mayInterruptIfRunning);
121
122    /**
123     * Returns {@code true} if this task was cancelled before it completed
124     * normally.
125     *
126     * @return {@code true} if this task was cancelled before it completed
127     */
128    boolean isCancelled();
129
130    /**
131     * Returns {@code true} if this task completed.
132     *
133     * Completion may be due to normal termination, an exception, or
134     * cancellation -- in all of these cases, this method will return
135     * {@code true}.
136     *
137     * @return {@code true} if this task completed
138     */
139    boolean isDone();
140
141    /**
142     * Waits if necessary for the computation to complete, and then
143     * retrieves its result.
144     *
145     * @return the computed result
146     * @throws CancellationException if the computation was cancelled
147     * @throws ExecutionException if the computation threw an
148     * exception
149     * @throws InterruptedException if the current thread was interrupted
150     * while waiting
151     */
152    V get() throws InterruptedException, ExecutionException;
153
154    /**
155     * Waits if necessary for at most the given time for the computation
156     * to complete, and then retrieves its result, if available.
157     *
158     * @param timeout the maximum time to wait
159     * @param unit the time unit of the timeout argument
160     * @return the computed result
161     * @throws CancellationException if the computation was cancelled
162     * @throws ExecutionException if the computation threw an
163     * exception
164     * @throws InterruptedException if the current thread was interrupted
165     * while waiting
166     * @throws TimeoutException if the wait timed out
167     */
168    V get(long timeout, TimeUnit unit)
169        throws InterruptedException, ExecutionException, TimeoutException;
170}
171