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.  Once the computation has completed,
 * the computation cannot 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>
 * @see FutureTask
 * @see Executor
 * @since 1.5
 * @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.12
Committed:	Sun Aug 31 13:33:13 2003 UTC (20 years, 9 months ago) by dl
Branch:	MAIN
Changes since 1.11:	+11 -13 lines
Log Message:	Removed non-standard tags and misc javadoc cleanup
#	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			* necessary until it is ready. Once the computation has completed,
16			* the computation cannot be restarted or cancelled.
17	tim	1.1	*
18			* <p>
19	dl	1.5	* <b>Sample Usage</b> (Note that the following classes are all
20			* made-up.) <p>
21	tim	1.1	* <pre>
22	dl	1.10	* interface ArchiveSearcher { String search(String target); }
23	tim	1.1	* class App {
24			* Executor executor = ...
25	dl	1.5	* ArchiveSearcher searcher = ...
26			* void showSearch(final String target) throws InterruptedException {
27	tim	1.7	* Future<String> future =
28			* new FutureTask<String>(new Callable<String>() {
29	dl	1.5	* public String call() {
30			* return searcher.search(target);
31	tim	1.1	* }});
32	dl	1.5	* executor.execute(future);
33			* displayOtherThings(); // do other things while searching
34	tim	1.1	* try {
35	dl	1.5	* displayText(future.get()); // use future
36	tim	1.8	* } catch (ExecutionException ex) { cleanup(); return; }
37	tim	1.1	* }
38			* }
39			* </pre>
40			*
41	dl	1.10	* The {@link Executors} class contains more convenient methods
42			* for common usages. For example, the above explicit
43			* construction could be replaced with:
44			* <pre>
45			* Future<String> future = Executors.execute(executor,
46			* new Callable<String>() {
47			* public String call() {
48			* return searcher.search(target);
49			* }});
50			* </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	tim	1.1	*/
56	tim	1.9	public interface Future<V> extends Cancellable {
57	tim	1.1
58			/**
59			* Waits if necessary for computation to complete, and then
60			* retrieves its result.
61			*
62			* @return computed result
63	dl	1.11	* @throws CancellationException if this future was cancelled.
64	dl	1.4	* @throws ExecutionException if underlying computation threw an
65			* exception
66			* @throws InterruptedException if current thread was interrupted
67			* while waiting
68	tim	1.1	*/
69			V get() throws InterruptedException, ExecutionException;
70
71			/**
72			* Waits if necessary for at most the given time for the computation
73			* to complete, and then retrieves its result.
74			*
75			* @param timeout the maximum time to wait
76			* @param granularity the time unit of the timeout argument
77			* @return computed result
78	dl	1.4	* @throws ExecutionException if underlying computation threw an
79			* exception
80			* @throws InterruptedException if current thread was interrupted
81			* while waiting
82	tim	1.1	* @throws TimeoutException if the wait timed out
83			*/
84			V get(long timeout, TimeUnit granularity)
85			throws InterruptedException, ExecutionException, TimeoutException;
86			}
87
88
89