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 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
 * @param <V> The result type returned by this Future
 */
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 unit 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 unit)
        throws InterruptedException, ExecutionException, TimeoutException;
}


Revision:	1.15
Committed:	Sat Oct 18 12:29:33 2003 UTC (20 years, 7 months ago) by dl
Branch:	MAIN
CVS Tags:	JSR166_NOV3_FREEZE
Changes since 1.14:	+1 -0 lines
Log Message:	Added docs for type params
#	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	dl	1.13	* the computation cannot be 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	dl	1.15	* @param <V> The result type returned by this Future
56	tim	1.1	*/
57	tim	1.9	public interface Future<V> extends Cancellable {
58	tim	1.1
59			/**
60			* Waits if necessary for computation to complete, and then
61			* retrieves its result.
62			*
63			* @return computed result
64	dl	1.11	* @throws CancellationException if this future was cancelled.
65	dl	1.4	* @throws ExecutionException if underlying computation threw an
66			* exception
67			* @throws InterruptedException if current thread was interrupted
68			* while waiting
69	tim	1.1	*/
70			V get() throws InterruptedException, ExecutionException;
71
72			/**
73			* Waits if necessary for at most the given time for the computation
74			* to complete, and then retrieves its result.
75			*
76			* @param timeout the maximum time to wait
77	dl	1.14	* @param unit the time unit of the timeout argument
78	tim	1.1	* @return computed result
79	dl	1.4	* @throws ExecutionException if underlying computation threw an
80			* exception
81			* @throws InterruptedException if current thread was interrupted
82			* while waiting
83	tim	1.1	* @throws TimeoutException if the wait timed out
84			*/
85	dl	1.14	V get(long timeout, TimeUnit unit)
86	tim	1.1	throws InterruptedException, ExecutionException, TimeoutException;
87			}
88
89
90