165 lines
6.7 KiB
Java
165 lines
6.7 KiB
Java
/*
|
|
* 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. Oracle designates this
|
|
* particular file as subject to the "Classpath" exception as provided
|
|
* by Oracle 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 Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
|
|
* or visit www.oracle.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/publicdomain/zero/1.0/
|
|
*/
|
|
|
|
package java.util.concurrent;
|
|
|
|
/**
|
|
* A {@code Future} 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
|
|
* {@code get} when the computation has completed, blocking if
|
|
* necessary until it is ready. Cancellation is performed by the
|
|
* {@code cancel} 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 {@code Future} for the sake
|
|
* of cancellability but not provide a usable result, you can
|
|
* declare types of the form {@code Future<?>} and
|
|
* return {@code null} as a result of the underlying task.
|
|
*
|
|
* <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(String target) throws InterruptedException {
|
|
* Callable<String> task = () -> searcher.search(target);
|
|
* Future<String> future = executor.submit(task);
|
|
* 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<>(task);
|
|
* 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> {
|
|
|
|
/**
|
|
* Attempts to cancel execution of this task. This method has no
|
|
* effect if the task is already completed or cancelled, or could
|
|
* not be cancelled for some other reason. Otherwise, if this
|
|
* task has not started when {@code cancel} is called, this task
|
|
* should never run. If the task has already started, then the
|
|
* {@code mayInterruptIfRunning} parameter determines whether the
|
|
* thread executing this task (when known by the implementation)
|
|
* is interrupted in an attempt to stop the task.
|
|
*
|
|
* <p>The return value from this method does not necessarily
|
|
* indicate whether the task is now cancelled; use {@link
|
|
* #isCancelled}.
|
|
*
|
|
* @param mayInterruptIfRunning {@code true} if the thread
|
|
* executing this task should be interrupted (if the thread is
|
|
* known to the implementation); otherwise, in-progress tasks are
|
|
* allowed to complete
|
|
* @return {@code false} if the task could not be cancelled,
|
|
* typically because it has already completed; {@code true}
|
|
* otherwise. If two or more threads cause a task to be cancelled,
|
|
* then at least one of them returns {@code true}. Implementations
|
|
* may provide stronger guarantees.
|
|
*/
|
|
boolean cancel(boolean mayInterruptIfRunning);
|
|
|
|
/**
|
|
* Returns {@code true} if this task was cancelled before it completed
|
|
* normally.
|
|
*
|
|
* @return {@code true} if this task was cancelled before it completed
|
|
*/
|
|
boolean isCancelled();
|
|
|
|
/**
|
|
* Returns {@code true} if this task completed.
|
|
*
|
|
* Completion may be due to normal termination, an exception, or
|
|
* cancellation -- in all of these cases, this method will return
|
|
* {@code true}.
|
|
*
|
|
* @return {@code true} 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;
|
|
}
|