util/concurrent/Future.java

/*
 * @(#)Future.java
 */

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 when the computation
 * has completed.  The <tt>get</tt> method will block until the computation
 * has completed.  Once the computation has completed, the result cannot
 * be changed, nor can the computation be restarted or 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 {
 *   Executor executor = ...
 *   ArchiveSearcher searcher = ...
 *   void showSearch(final String target) throws InterruptedException {
 *     Future&lt;String&gt; future =
 *       new FutureTask&lt;String&gt;(new Callable&lt;String&gt;() {
 *         public String call() {
 *           return searcher.search(target);
 *       }});
 *     executor.execute(future);
 *     displayOtherThings(); // do other things while searching
 *     try {
 *       displayText(future.get()); // use future
 *     } catch (ExecutionException ex) { cleanup(); return; }
 *   }
 * }
 * </pre>
 *
 * The {@link Executors} class contains more convenient methods 
 * for common usages. For example, the above explicit
 * construction could be replaced with:
 * <pre>
 * Future&lt;String&gt; future = Executors.execute(executor, 
 *    new Callable&lt;String&gt;() {
 *       public String call() {
 *         return searcher.search(target);
 *    }});
 * </pre>
 * @since 1.5
 * @see FutureTask
 * @see Executor
 *
 * @spec JSR-166
 * @revised $Date: 2003/08/24 14:47:31 $
 * @editor $Author: dl $
 * @author Doug Lea
 */
public interface Future<V> extends Cancellable {

    /**
     * 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 granularity 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 granularity)
        throws InterruptedException, ExecutionException, TimeoutException;
}


Revision:	1.11
Committed:	Fri Aug 29 14:09:52 2003 UTC (20 years, 9 months ago) by dl
Branch:	MAIN
Changes since 1.10:	+3 -3 lines
Log Message:	Avoid ABA problem in CHP; fix other javadocs
#	User	Rev	Content
1	tim	1.1	/*
2			* @(#)Future.java
3			*/
4
5			package java.util.concurrent;
6
7			/**
8			* A <tt>Future</tt> represents the result of an asynchronous computation.
9			* Methods are provided to check if the computation is complete,
10			* to wait for its completion, and to retrieve the result of the
11			* computation. The result can only be retrieved when the computation
12			* has completed. The <tt>get</tt> method will block until the computation
13			* has completed. Once the computation has completed, the result cannot
14			* be changed, nor can the computation be restarted or cancelled.
15			*
16			* <p>
17	dl	1.5	* <b>Sample Usage</b> (Note that the following classes are all
18			* made-up.) <p>
19	tim	1.1	* <pre>
20	dl	1.10	* interface ArchiveSearcher { String search(String target); }
21	tim	1.1	* class App {
22			* Executor executor = ...
23	dl	1.5	* ArchiveSearcher searcher = ...
24			* void showSearch(final String target) throws InterruptedException {
25	tim	1.7	* Future<String> future =
26			* new FutureTask<String>(new Callable<String>() {
27	dl	1.5	* public String call() {
28			* return searcher.search(target);
29	tim	1.1	* }});
30	dl	1.5	* executor.execute(future);
31			* displayOtherThings(); // do other things while searching
32	tim	1.1	* try {
33	dl	1.5	* displayText(future.get()); // use future
34	tim	1.8	* } catch (ExecutionException ex) { cleanup(); return; }
35	tim	1.1	* }
36			* }
37			* </pre>
38			*
39	dl	1.10	* The {@link Executors} class contains more convenient methods
40			* for common usages. For example, the above explicit
41			* construction could be replaced with:
42			* <pre>
43			* Future<String> future = Executors.execute(executor,
44			* new Callable<String>() {
45			* public String call() {
46			* return searcher.search(target);
47			* }});
48			* </pre>
49	tim	1.1	* @since 1.5
50			* @see FutureTask
51			* @see Executor
52			*
53			* @spec JSR-166
54	dl	1.11	* @revised $Date: 2003/08/24 14:47:31 $
55			* @editor $Author: dl $
56	dl	1.4	* @author Doug Lea
57	tim	1.1	*/
58	tim	1.9	public interface Future<V> extends Cancellable {
59	tim	1.1
60			/**
61			* Waits if necessary for computation to complete, and then
62			* retrieves its result.
63			*
64			* @return computed result
65	dl	1.11	* @throws CancellationException if this future was cancelled.
66	dl	1.4	* @throws ExecutionException if underlying computation threw an
67			* exception
68			* @throws InterruptedException if current thread was interrupted
69			* while waiting
70	tim	1.1	*/
71			V get() throws InterruptedException, ExecutionException;
72
73			/**
74			* Waits if necessary for at most the given time for the computation
75			* to complete, and then retrieves its result.
76			*
77			* @param timeout the maximum time to wait
78			* @param granularity the time unit of the timeout argument
79			* @return computed result
80	dl	1.4	* @throws ExecutionException if underlying computation threw an
81			* exception
82			* @throws InterruptedException if current thread was interrupted
83			* while waiting
84	tim	1.1	* @throws TimeoutException if the wait timed out
85			*/
86			V get(long timeout, TimeUnit granularity)
87			throws InterruptedException, ExecutionException, TimeoutException;
88			}
89
90
91