1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/rt/emul/compact/src/main/java/java/util/concurrent/Future.java Sat Mar 19 10:46:31 2016 +0100
1.3 @@ -0,0 +1,169 @@
1.4 +/*
1.5 + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
1.6 + *
1.7 + * This code is free software; you can redistribute it and/or modify it
1.8 + * under the terms of the GNU General Public License version 2 only, as
1.9 + * published by the Free Software Foundation. Oracle designates this
1.10 + * particular file as subject to the "Classpath" exception as provided
1.11 + * by Oracle in the LICENSE file that accompanied this code.
1.12 + *
1.13 + * This code is distributed in the hope that it will be useful, but WITHOUT
1.14 + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
1.15 + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
1.16 + * version 2 for more details (a copy is included in the LICENSE file that
1.17 + * accompanied this code).
1.18 + *
1.19 + * You should have received a copy of the GNU General Public License version
1.20 + * 2 along with this work; if not, write to the Free Software Foundation,
1.21 + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
1.22 + *
1.23 + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
1.24 + * or visit www.oracle.com if you need additional information or have any
1.25 + * questions.
1.26 + */
1.27 +
1.28 +/*
1.29 + * This file is available under and governed by the GNU General Public
1.30 + * License version 2 only, as published by the Free Software Foundation.
1.31 + * However, the following notice accompanied the original version of this
1.32 + * file:
1.33 + *
1.34 + * Written by Doug Lea with assistance from members of JCP JSR-166
1.35 + * Expert Group and released to the public domain, as explained at
1.36 + * http://creativecommons.org/publicdomain/zero/1.0/
1.37 + */
1.38 +
1.39 +package java.util.concurrent;
1.40 +
1.41 +/**
1.42 + * A <tt>Future</tt> represents the result of an asynchronous
1.43 + * computation. Methods are provided to check if the computation is
1.44 + * complete, to wait for its completion, and to retrieve the result of
1.45 + * the computation. The result can only be retrieved using method
1.46 + * <tt>get</tt> when the computation has completed, blocking if
1.47 + * necessary until it is ready. Cancellation is performed by the
1.48 + * <tt>cancel</tt> method. Additional methods are provided to
1.49 + * determine if the task completed normally or was cancelled. Once a
1.50 + * computation has completed, the computation cannot be cancelled.
1.51 + * If you would like to use a <tt>Future</tt> for the sake
1.52 + * of cancellability but not provide a usable result, you can
1.53 + * declare types of the form {@code Future<?>} and
1.54 + * return <tt>null</tt> as a result of the underlying task.
1.55 + *
1.56 + * <p>
1.57 + * <b>Sample Usage</b> (Note that the following classes are all
1.58 + * made-up.) <p>
1.59 + * <pre> {@code
1.60 + * interface ArchiveSearcher { String search(String target); }
1.61 + * class App {
1.62 + * ExecutorService executor = ...
1.63 + * ArchiveSearcher searcher = ...
1.64 + * void showSearch(final String target)
1.65 + * throws InterruptedException {
1.66 + * Future<String> future
1.67 + * = executor.submit(new Callable<String>() {
1.68 + * public String call() {
1.69 + * return searcher.search(target);
1.70 + * }});
1.71 + * displayOtherThings(); // do other things while searching
1.72 + * try {
1.73 + * displayText(future.get()); // use future
1.74 + * } catch (ExecutionException ex) { cleanup(); return; }
1.75 + * }
1.76 + * }}</pre>
1.77 + *
1.78 + * The {@link FutureTask} class is an implementation of <tt>Future</tt> that
1.79 + * implements <tt>Runnable</tt>, and so may be executed by an <tt>Executor</tt>.
1.80 + * For example, the above construction with <tt>submit</tt> could be replaced by:
1.81 + * <pre> {@code
1.82 + * FutureTask<String> future =
1.83 + * new FutureTask<String>(new Callable<String>() {
1.84 + * public String call() {
1.85 + * return searcher.search(target);
1.86 + * }});
1.87 + * executor.execute(future);}</pre>
1.88 + *
1.89 + * <p>Memory consistency effects: Actions taken by the asynchronous computation
1.90 + * <a href="package-summary.html#MemoryVisibility"> <i>happen-before</i></a>
1.91 + * actions following the corresponding {@code Future.get()} in another thread.
1.92 + *
1.93 + * @see FutureTask
1.94 + * @see Executor
1.95 + * @since 1.5
1.96 + * @author Doug Lea
1.97 + * @param <V> The result type returned by this Future's <tt>get</tt> method
1.98 + */
1.99 +public interface Future<V> {
1.100 +
1.101 + /**
1.102 + * Attempts to cancel execution of this task. This attempt will
1.103 + * fail if the task has already completed, has already been cancelled,
1.104 + * or could not be cancelled for some other reason. If successful,
1.105 + * and this task has not started when <tt>cancel</tt> is called,
1.106 + * this task should never run. If the task has already started,
1.107 + * then the <tt>mayInterruptIfRunning</tt> parameter determines
1.108 + * whether the thread executing this task should be interrupted in
1.109 + * an attempt to stop the task.
1.110 + *
1.111 + * <p>After this method returns, subsequent calls to {@link #isDone} will
1.112 + * always return <tt>true</tt>. Subsequent calls to {@link #isCancelled}
1.113 + * will always return <tt>true</tt> if this method returned <tt>true</tt>.
1.114 + *
1.115 + * @param mayInterruptIfRunning <tt>true</tt> if the thread executing this
1.116 + * task should be interrupted; otherwise, in-progress tasks are allowed
1.117 + * to complete
1.118 + * @return <tt>false</tt> if the task could not be cancelled,
1.119 + * typically because it has already completed normally;
1.120 + * <tt>true</tt> otherwise
1.121 + */
1.122 + boolean cancel(boolean mayInterruptIfRunning);
1.123 +
1.124 + /**
1.125 + * Returns <tt>true</tt> if this task was cancelled before it completed
1.126 + * normally.
1.127 + *
1.128 + * @return <tt>true</tt> if this task was cancelled before it completed
1.129 + */
1.130 + boolean isCancelled();
1.131 +
1.132 + /**
1.133 + * Returns <tt>true</tt> if this task completed.
1.134 + *
1.135 + * Completion may be due to normal termination, an exception, or
1.136 + * cancellation -- in all of these cases, this method will return
1.137 + * <tt>true</tt>.
1.138 + *
1.139 + * @return <tt>true</tt> if this task completed
1.140 + */
1.141 + boolean isDone();
1.142 +
1.143 + /**
1.144 + * Waits if necessary for the computation to complete, and then
1.145 + * retrieves its result.
1.146 + *
1.147 + * @return the computed result
1.148 + * @throws CancellationException if the computation was cancelled
1.149 + * @throws ExecutionException if the computation threw an
1.150 + * exception
1.151 + * @throws InterruptedException if the current thread was interrupted
1.152 + * while waiting
1.153 + */
1.154 + V get() throws InterruptedException, ExecutionException;
1.155 +
1.156 + /**
1.157 + * Waits if necessary for at most the given time for the computation
1.158 + * to complete, and then retrieves its result, if available.
1.159 + *
1.160 + * @param timeout the maximum time to wait
1.161 + * @param unit the time unit of the timeout argument
1.162 + * @return the computed result
1.163 + * @throws CancellationException if the computation was cancelled
1.164 + * @throws ExecutionException if the computation threw an
1.165 + * exception
1.166 + * @throws InterruptedException if the current thread was interrupted
1.167 + * while waiting
1.168 + * @throws TimeoutException if the wait timed out
1.169 + */
1.170 + V get(long timeout, TimeUnit unit)
1.171 + throws InterruptedException, ExecutionException, TimeoutException;
1.172 +}