Future源码分析

Future源码分析

/**
 * Create by ~JH~ on 2018/4/10
 */
import java.util.concurrent.ExecutionException;
import java.util.concurrent.TimeUnit;

/**
 *Future代表一步计算的结果。他的方法都检查计算是否完成，为了等待完成和恢复计算结果。
 *当计算完成，结果只能使用get方法恢复如果有必要会一直阻塞到准备好。
 * 取消使用cancel方法，另外的方法被提供来判定任务是被正常完成了还是被取消了。
 *一旦以此计算王成，计算不能被取消。如果你想使用Future来达到取消的目的而不是提供一个使用中的方法，
 * 你可以声明一个类型Future<?>并且返回一个null作为基础任务的结果。
 * <p>
 * <b>Sample Usage</b> (Note that the following classes are all
 * made-up.)
 * <pre> {@code
 * interface ArchiveSearcher { String search(String target); }
 * class App {
 *   ExecutorService executor = ...
 *   ArchiveSearcher searcher = ...
 *   void showSearch(final String target)
 *       throws InterruptedException {
 *     Future<String> future
 *       = executor.submit(new Callable<String>() {
 *         public String call() {
 *             return searcher.search(target);
 *         }});
 *     displayOtherThings(); // do other things while searching
 *     try {
 *       displayText(future.get()); // use future
 *     } catch (ExecutionException ex) { cleanup(); return; }
 *   }
 * }}</pre>
 *
 * The {@link FutureTask} class is an implementation of {@code Future} that
 * implements {@code Runnable}, and so may be executed by an {@code Executor}.
 * For example, the above construction with {@code submit} could be replaced by:
 *  <pre> {@code
 * FutureTask<String> future =
 *   new FutureTask<String>(new Callable<String>() {
 *     public String call() {
 *       return searcher.search(target);
 *   }});
 * executor.execute(future);}</pre>
 *
 * <p>Memory consistency effects: Actions taken by the asynchronous computation
 * <a href="package-summary.html#MemoryVisibility"> <i>happen-before</i></a>
 * actions following the corresponding {@code Future.get()} in another thread.
 *
 * @see FutureTask
 * @see Executor
 * @since 1.5
 * @author Doug Lea
 * @param <V> The result type returned by this Future's {@code get} method
 */
public interface Future<V> {

    /**
     *尝试取消执行中的任务，如果已经完成、已经取消或者其他原因就会执行失败，
     * 如果成功，当cancel调用并且任务没有开始，任务就永远不会执行。如果任务已经开始，
     * 然后mayInterruptIfRunning这个参数判断这个执行的线程在尝试停止任务的时候是否应该被中断

     *在这个方法返回之后，如果返回True，随后调用的isDone，他总是返回true，再调用isCancelled也会返回true

     * 如果任务不应该被中断，典型的是他已经完成了就是false
     * {@code true} otherwise
     */
    boolean cancel(boolean mayInterruptIfRunning);

    /**
     *在正常完成之前取消就返回True
     */
    boolean isCancelled();

    /**
     *任务已经完成就返回真
     *正常结束，异常或者取消都会返回true
     */
    boolean isDone();

    /**
     * Waits if necessary for the computation to complete, and then
     * retrieves its result.
     *
     * @return the computed result
     * @throws CancellationException 计算取消
     * @throws ExecutionException if the computation threw an
     * exception
     * @throws InterruptedException if the current thread was interrupted
     * while waiting
     */
    V get() throws InterruptedException, ExecutionException;

    /**
     *在给的时间内等待完成并且恢复它的结果
     * @param timeout the maximum time to wait
     * @param unit the time unit of the timeout argument
     * @return the computed result
     * @throws CancellationException if the computation was cancelled
     * @throws ExecutionException if the computation threw an
     * exception
     * @throws InterruptedException if the current thread was interrupted
     * while waiting
     * @throws TimeoutException if the wait timed out
     */
    V get(long timeout, TimeUnit unit)
            throws InterruptedException, ExecutionException, TimeoutException;
}