/*

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

 *

 * This code is free software; you can redistribute it and/or modify it

 * under the terms of the GNU General Public License version 2 only, as

 * published by the Free Software Foundation.  Sun designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Sun in the LICENSE file that accompanied this code.

 *

 * This code is distributed in the hope that it will be useful, but WITHOUT

 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

 * version 2 for more details (a copy is included in the LICENSE file that

 * accompanied this code).

 *

 * You should have received a copy of the GNU General Public License version

 * 2 along with this work; if not, write to the Free Software Foundation,

 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

 *

 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,

 * CA 95054 USA or visit www.sun.com if you need additional information or

 * have any questions.

 */

/*

 * This file is available under and governed by the GNU General Public

 * License version 2 only, as published by the Free Software Foundation.

 * However, the following notice accompanied the original version of this

 * file:

 *

 * Written by Doug Lea with assistance from members of JCP JSR-166

 * Expert Group and released to the public domain, as explained at

 * http://creativecommons.org/licenses/publicdomain

 */

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.

 * If you would like to use a <tt>Future</tt> for the sake

 * of cancellability but not provide a usable result, you can

 * declare types of the form <tt>Future&lt;?&gt;</tt> and

 * return <tt>null</tt> as a result of the underlying task.

 *

 * <p>

 * <b>Sample Usage</b> (Note that the following classes are all

 * made-up.) <p>

 * <pre>

 * 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 <tt>Future</tt> that

 * implements <tt>Runnable</tt>, and so may be executed by an <tt>Executor</tt>.

 * For example, the above construction with <tt>submit</tt> could be replaced by:

 * <pre>

 *     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 <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, has 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>mayInterruptIfRunning</tt> parameter determines

     * whether the thread executing this task should be interrupted in

     * an attempt to stop the task.

     *

     * <p>After this method returns, subsequent calls to {@link #isDone} will

     * always return <tt>true</tt>.  Subsequent calls to {@link #isCancelled}

     * will always return <tt>true</tt> if this method returned <tt>true</tt>.

     *

     * @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 it 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 this 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 the computation to complete, and then

     * retrieves its result.

     *

     * @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

     */

    V get() throws InterruptedException, ExecutionException;

    /**

     * Waits if necessary for at most the given time for the computation

     * to complete, and then retrieves its result, if available.

     *

     * @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;

}