GNU Classpath (0.97.2) | |
Frames | No Frames |
1: /* 2: * Written by Doug Lea with assistance from members of JCP JSR-166 3: * Expert Group and released to the public domain, as explained at 4: * http://creativecommons.org/licenses/publicdomain 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: * If you would like to use a <tt>Future</tt> for the sake 20: * of cancellability but not provide a usable result, you can 21: * declare types of the form <tt>Future<?></tt> and 22: * return <tt>null</tt> as a result of the underlying task. 23: * 24: * <p> 25: * <b>Sample Usage</b> (Note that the following classes are all 26: * made-up.) <p> 27: * <pre> 28: * interface ArchiveSearcher { String search(String target); } 29: * class App { 30: * ExecutorService executor = ... 31: * ArchiveSearcher searcher = ... 32: * void showSearch(final String target) 33: * throws InterruptedException { 34: * Future<String> future 35: * = executor.submit(new Callable<String>() { 36: * public String call() { 37: * return searcher.search(target); 38: * }}); 39: * displayOtherThings(); // do other things while searching 40: * try { 41: * displayText(future.get()); // use future 42: * } catch (ExecutionException ex) { cleanup(); return; } 43: * } 44: * } 45: * </pre> 46: * 47: * The {@link FutureTask} class is an implementation of <tt>Future</tt> that 48: * implements <tt>Runnable</tt>, and so may be executed by an <tt>Executor</tt>. 49: * For example, the above construction with <tt>submit</tt> could be replaced by: 50: * <pre> 51: * FutureTask<String> future = 52: * new FutureTask<String>(new Callable<String>() { 53: * public String call() { 54: * return searcher.search(target); 55: * }}); 56: * executor.execute(future); 57: * </pre> 58: * 59: * <p>Memory consistency effects: Actions taken by the asynchronous computation 60: * <a href="package-summary.html#MemoryVisibility"> <i>happen-before</i></a> 61: * actions following the corresponding {@code Future.get()} in another thread. 62: * 63: * @see FutureTask 64: * @see Executor 65: * @since 1.5 66: * @author Doug Lea 67: * @param <V> The result type returned by this Future's <tt>get</tt> method 68: */ 69: public interface Future<V> { 70: 71: /** 72: * Attempts to cancel execution of this task. This attempt will 73: * fail if the task has already completed, has already been cancelled, 74: * or could not be cancelled for some other reason. If successful, 75: * and this task has not started when <tt>cancel</tt> is called, 76: * this task should never run. If the task has already started, 77: * then the <tt>mayInterruptIfRunning</tt> parameter determines 78: * whether the thread executing this task should be interrupted in 79: * an attempt to stop the task. 80: * 81: * <p>After this method returns, subsequent calls to {@link #isDone} will 82: * always return <tt>true</tt>. Subsequent calls to {@link #isCancelled} 83: * will always return <tt>true</tt> if this method returned <tt>true</tt>. 84: * 85: * @param mayInterruptIfRunning <tt>true</tt> if the thread executing this 86: * task should be interrupted; otherwise, in-progress tasks are allowed 87: * to complete 88: * @return <tt>false</tt> if the task could not be cancelled, 89: * typically because it has already completed normally; 90: * <tt>true</tt> otherwise 91: */ 92: boolean cancel(boolean mayInterruptIfRunning); 93: 94: /** 95: * Returns <tt>true</tt> if this task was cancelled before it completed 96: * normally. 97: * 98: * @return <tt>true</tt> if this task was cancelled before it completed 99: */ 100: boolean isCancelled(); 101: 102: /** 103: * Returns <tt>true</tt> if this task completed. 104: * 105: * Completion may be due to normal termination, an exception, or 106: * cancellation -- in all of these cases, this method will return 107: * <tt>true</tt>. 108: * 109: * @return <tt>true</tt> if this task completed 110: */ 111: boolean isDone(); 112: 113: /** 114: * Waits if necessary for the computation to complete, and then 115: * retrieves its result. 116: * 117: * @return the computed result 118: * @throws CancellationException if the computation was cancelled 119: * @throws ExecutionException if the computation threw an 120: * exception 121: * @throws InterruptedException if the current thread was interrupted 122: * while waiting 123: */ 124: V get() throws InterruptedException, ExecutionException; 125: 126: /** 127: * Waits if necessary for at most the given time for the computation 128: * to complete, and then retrieves its result, if available. 129: * 130: * @param timeout the maximum time to wait 131: * @param unit the time unit of the timeout argument 132: * @return the computed result 133: * @throws CancellationException if the computation was cancelled 134: * @throws ExecutionException if the computation threw an 135: * exception 136: * @throws InterruptedException if the current thread was interrupted 137: * while waiting 138: * @throws TimeoutException if the wait timed out 139: */ 140: V get(long timeout, TimeUnit unit) 141: throws InterruptedException, ExecutionException, TimeoutException; 142: }
GNU Classpath (0.97.2) |