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.  Cancellation is performed by the
 * <tt>cancel</tt> method.  Additional methods are provided to
 * determine if the task completed normally or was cancelled. Once a
 * 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's <tt>get</tt> method
 */
public interface Future<V> {

    /**
     * Attempts to cancel execution of this task.  This attempt will
     * fail if the task has already completed, already been cancelled,
     * or could not be cancelled for some other reason. If successful,
     * and this task has not started when <tt>cancel</tt> is called,
     * this task should never run.  If the task has already started,
     * then the <tt>interruptIfRunning</tt> parameter determines
     * whether the thread executing this task should be interrupted in
     * an attempt to stop the task.
     *
     * @param mayInterruptIfRunning <tt>true</tt> if the thread executing this
     * task should be interrupted; otherwise, in-progress tasks are allowed
     * to complete
     * @return <tt>false</tt> if the task could not be cancelled,
     * typically because is has already completed normally;
     * <tt>true</tt> otherwise
     */
    boolean cancel(boolean mayInterruptIfRunning);

    /**
     * Returns <tt>true</tt> if this task was cancelled before it completed
     * normally.
     *
     * @return <tt>true</tt> if task was cancelled before it completed
     */
    boolean isCancelled();

    /**
     * Returns <tt>true</tt> if this task completed.  
     *
     * Completion may be due to normal termination, an exception, or
     * cancellation -- in all of these cases, this method will return
     * <tt>true</tt>.
     * 
     * @return <tt>true</tt> if this task completed.
     */
    boolean isDone();

    /**
     * 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.17
Committed:	Thu Dec 4 20:54:29 2003 UTC (20 years, 6 months ago) by dl
Branch:	MAIN
CVS Tags:	JSR166_DEC9_PRE_ES_SUBMIT, JSR166_DEC9_POST_ES_SUBMIT
Changes since 1.16:	+43 -3 lines
Log Message:	Revised tests for revised Future classes
#	Content
1	/*
2	* 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	*/
6
7	package java.util.concurrent;
8
9	/**
10	* 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. Cancellation is performed by the
16	* <tt>cancel</tt> 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	*
20	* <p>
21	* <b>Sample Usage</b> (Note that the following classes are all
22	* made-up.) <p>
23	* <pre>
24	* interface ArchiveSearcher { String search(String target); }
25	* class App {
26	* Executor executor = ...
27	* ArchiveSearcher searcher = ...
28	* void showSearch(final String target) throws InterruptedException {
29	* Future<String> future =
30	* new FutureTask<String>(new Callable<String>() {
31	* public String call() {
32	* return searcher.search(target);
33	* }});
34	* executor.execute(future);
35	* displayOtherThings(); // do other things while searching
36	* try {
37	* displayText(future.get()); // use future
38	* } catch (ExecutionException ex) { cleanup(); return; }
39	* }
40	* }
41	* </pre>
42	*
43	* The {@link Executors} class contains more convenient methods
44	* for common usages. For example, the above explicit
45	* construction could be replaced with:
46	* <pre>
47	* Future<String> future = Executors.execute(executor,
48	* new Callable<String>() {
49	* public String call() {
50	* return searcher.search(target);
51	* }});
52	* </pre>
53	* @see FutureTask
54	* @see Executor
55	* @since 1.5
56	* @author Doug Lea
57	* @param <V> The result type returned by this Future's <tt>get</tt> method
58	*/
59	public interface Future<V> {
60
61	/**
62	* Attempts to cancel execution of this task. This attempt will
63	* fail if the task has already completed, already been cancelled,
64	* or could not be cancelled for some other reason. If successful,
65	* and this task has not started when <tt>cancel</tt> is called,
66	* this task should never run. If the task has already started,
67	* then the <tt>interruptIfRunning</tt> parameter determines
68	* whether the thread executing this task should be interrupted in
69	* an attempt to stop the task.
70	*
71	* @param mayInterruptIfRunning <tt>true</tt> if the thread executing this
72	* task should be interrupted; otherwise, in-progress tasks are allowed
73	* to complete
74	* @return <tt>false</tt> if the task could not be cancelled,
75	* typically because is has already completed normally;
76	* <tt>true</tt> otherwise
77	*/
78	boolean cancel(boolean mayInterruptIfRunning);
79
80	/**
81	* Returns <tt>true</tt> if this task was cancelled before it completed
82	* normally.
83	*
84	* @return <tt>true</tt> if task was cancelled before it completed
85	*/
86	boolean isCancelled();
87
88	/**
89	* Returns <tt>true</tt> if this task completed.
90	*
91	* Completion may be due to normal termination, an exception, or
92	* cancellation -- in all of these cases, this method will return
93	* <tt>true</tt>.
94	*
95	* @return <tt>true</tt> if this task completed.
96	*/
97	boolean isDone();
98
99	/**
100	* Waits if necessary for computation to complete, and then
101	* retrieves its result.
102	*
103	* @return computed result
104	* @throws CancellationException if this future was cancelled.
105	* @throws ExecutionException if underlying computation threw an
106	* exception
107	* @throws InterruptedException if current thread was interrupted
108	* while waiting
109	*/
110	V get() throws InterruptedException, ExecutionException;
111
112	/**
113	* Waits if necessary for at most the given time for the computation
114	* to complete, and then retrieves its result.
115	*
116	* @param timeout the maximum time to wait
117	* @param unit the time unit of the timeout argument
118	* @return computed result
119	* @throws ExecutionException if underlying computation threw an
120	* exception
121	* @throws InterruptedException if current thread was interrupted
122	* while waiting
123	* @throws TimeoutException if the wait timed out
124	*/
125	V get(long timeout, TimeUnit unit)
126	throws InterruptedException, ExecutionException, TimeoutException;
127	}
128
129
130