001: /*
002: * Written by Doug Lea with assistance from members of JCP JSR-166
003: * Expert Group and released to the public domain, as explained at
004: * http://creativecommons.org/licenses/publicdomain
005: */
006:
007: package java.util.concurrent;
008:
009: /**
010: * A <tt>Future</tt> represents the result of an asynchronous
011: * computation. Methods are provided to check if the computation is
012: * complete, to wait for its completion, and to retrieve the result of
013: * the computation. The result can only be retrieved using method
014: * <tt>get</tt> when the computation has completed, blocking if
015: * necessary until it is ready. Cancellation is performed by the
016: * <tt>cancel</tt> method. Additional methods are provided to
017: * determine if the task completed normally or was cancelled. Once a
018: * computation has completed, the computation cannot be cancelled.
019: * If you would like to use a <tt>Future</tt> for the sake
020: * of cancellability but not provide a usable result, you can
021: * declare types of the form <tt>Future<?></tt> and
022: * return <tt>null</tt> as a result of the underlying task.
023: *
024: * <p>
025: * <b>Sample Usage</b> (Note that the following classes are all
026: * made-up.) <p>
027: * <pre>
028: * interface ArchiveSearcher { String search(String target); }
029: * class App {
030: * ExecutorService executor = ...
031: * ArchiveSearcher searcher = ...
032: * void showSearch(final String target) throws InterruptedException {
033: * Future<String> future = executor.submit(new Callable<String>() {
034: * public String call() { return searcher.search(target); }
035: * });
036: * displayOtherThings(); // do other things while searching
037: * try {
038: * displayText(future.get()); // use future
039: * } catch (ExecutionException ex) { cleanup(); return; }
040: * }
041: * }
042: * </pre>
043: *
044: * The {@link FutureTask} class is an implementation of <tt>Future</tt> that
045: * implements <tt>Runnable</tt>, and so may be executed by an <tt>Executor</tt>.
046: * For example, the above construction with <tt>submit</tt> could be replaced by:
047: * <pre>
048: * FutureTask<String> future =
049: * new FutureTask<String>(new Callable<String>() {
050: * public String call() {
051: * return searcher.search(target);
052: * }});
053: * executor.execute(future);
054: * </pre>
055: * @see FutureTask
056: * @see Executor
057: * @since 1.5
058: * @author Doug Lea
059: * @param <V> The result type returned by this Future's <tt>get</tt> method
060: */
061: public interface Future<V> {
062:
063: /**
064: * Attempts to cancel execution of this task. This attempt will
065: * fail if the task has already completed, already been cancelled,
066: * or could not be cancelled for some other reason. If successful,
067: * and this task has not started when <tt>cancel</tt> is called,
068: * this task should never run. If the task has already started,
069: * then the <tt>mayInterruptIfRunning</tt> parameter determines
070: * whether the thread executing this task should be interrupted in
071: * an attempt to stop the task.
072: *
073: * @param mayInterruptIfRunning <tt>true</tt> if the thread executing this
074: * task should be interrupted; otherwise, in-progress tasks are allowed
075: * to complete
076: * @return <tt>false</tt> if the task could not be cancelled,
077: * typically because it has already completed normally;
078: * <tt>true</tt> otherwise
079: */
080: boolean cancel(boolean mayInterruptIfRunning);
081:
082: /**
083: * Returns <tt>true</tt> if this task was cancelled before it completed
084: * normally.
085: *
086: * @return <tt>true</tt> if task was cancelled before it completed
087: */
088: boolean isCancelled();
089:
090: /**
091: * Returns <tt>true</tt> if this task completed.
092: *
093: * Completion may be due to normal termination, an exception, or
094: * cancellation -- in all of these cases, this method will return
095: * <tt>true</tt>.
096: *
097: * @return <tt>true</tt> if this task completed.
098: */
099: boolean isDone();
100:
101: /**
102: * Waits if necessary for the computation to complete, and then
103: * retrieves its result.
104: *
105: * @return the computed result
106: * @throws CancellationException if the computation was cancelled
107: * @throws ExecutionException if the computation threw an
108: * exception
109: * @throws InterruptedException if the current thread was interrupted
110: * while waiting
111: */
112: V get() throws InterruptedException, ExecutionException;
113:
114: /**
115: * Waits if necessary for at most the given time for the computation
116: * to complete, and then retrieves its result, if available.
117: *
118: * @param timeout the maximum time to wait
119: * @param unit the time unit of the timeout argument
120: * @return the computed result
121: * @throws CancellationException if the computation was cancelled
122: * @throws ExecutionException if the computation threw an
123: * exception
124: * @throws InterruptedException if the current thread was interrupted
125: * while waiting
126: * @throws TimeoutException if the wait timed out
127: */
128: V get(long timeout, TimeUnit unit) throws InterruptedException,
129: ExecutionException, TimeoutException;
130: }
|