My first initial commit with all of mine experimental changes.

Dmitry Kabak (userdima committed 13 years ago

Commit d37b88d1 parent 3f5b46618352 files · +2598093 −-8690Browse files

Showing the changes to java/pkg/java/util/concurrent/Future.java (1 of 18352 files). Show all

Unified · Split

java/pkg/java/util/concurrent/Future.java+169−0

@@ -0,0 +1,169 @@
	1	+/*
	2	+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
	3	+ *
	4	+ * This code is free software; you can redistribute it and/or modify it
	5	+ * under the terms of the GNU General Public License version 2 only, as
	6	+ * published by the Free Software Foundation. Oracle designates this
	7	+ * particular file as subject to the "Classpath" exception as provided
	8	+ * by Oracle in the LICENSE file that accompanied this code.
	9	+ *
	10	+ * This code is distributed in the hope that it will be useful, but WITHOUT
	11	+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
	12	+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
	13	+ * version 2 for more details (a copy is included in the LICENSE file that
	14	+ * accompanied this code).
	15	+ *
	16	+ * You should have received a copy of the GNU General Public License version
	17	+ * 2 along with this work; if not, write to the Free Software Foundation,
	18	+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
	19	+ *
	20	+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
	21	+ * or visit www.oracle.com if you need additional information or have any
	22	+ * questions.
	23	+ */
	24	+
	25	+/*
	26	+ * This file is available under and governed by the GNU General Public
	27	+ * License version 2 only, as published by the Free Software Foundation.
	28	+ * However, the following notice accompanied the original version of this
	29	+ * file:
	30	+ *
	31	+ * Written by Doug Lea with assistance from members of JCP JSR-166
	32	+ * Expert Group and released to the public domain, as explained at
	33	+ * http://creativecommons.org/publicdomain/zero/1.0/
	34	+ */
	35	+
	36	+package java.util.concurrent;
	37	+
	38	+/**
	39	+ * A <tt>Future</tt> represents the result of an asynchronous
	40	+ * computation. Methods are provided to check if the computation is
	41	+ * complete, to wait for its completion, and to retrieve the result of
	42	+ * the computation. The result can only be retrieved using method
	43	+ * <tt>get</tt> when the computation has completed, blocking if
	44	+ * necessary until it is ready. Cancellation is performed by the
	45	+ * <tt>cancel</tt> method. Additional methods are provided to
	46	+ * determine if the task completed normally or was cancelled. Once a
	47	+ * computation has completed, the computation cannot be cancelled.
	48	+ * If you would like to use a <tt>Future</tt> for the sake
	49	+ * of cancellability but not provide a usable result, you can
	50	+ * declare types of the form {@code Future<?>} and
	51	+ * return <tt>null</tt> as a result of the underlying task.
	52	+ *
	53	+ * <p>
	54	+ * <b>Sample Usage</b> (Note that the following classes are all
	55	+ * made-up.) <p>
	56	+ * <pre> {@code
	57	+ * interface ArchiveSearcher { String search(String target); }
	58	+ * class App {
	59	+ * ExecutorService executor = ...
	60	+ * ArchiveSearcher searcher = ...
	61	+ * void showSearch(final String target)
	62	+ * throws InterruptedException {
	63	+ * Future<String> future
	64	+ * = executor.submit(new Callable<String>() {
	65	+ * public String call() {
	66	+ * return searcher.search(target);
	67	+ * }});
	68	+ * displayOtherThings(); // do other things while searching
	69	+ * try {
	70	+ * displayText(future.get()); // use future
	71	+ * } catch (ExecutionException ex) { cleanup(); return; }
	72	+ * }
	73	+ * }}</pre>
	74	+ *
	75	+ * The {@link FutureTask} class is an implementation of <tt>Future</tt> that
	76	+ * implements <tt>Runnable</tt>, and so may be executed by an <tt>Executor</tt>.
	77	+ * For example, the above construction with <tt>submit</tt> could be replaced by:
	78	+ * <pre> {@code
	79	+ * FutureTask<String> future =
	80	+ * new FutureTask<String>(new Callable<String>() {
	81	+ * public String call() {
	82	+ * return searcher.search(target);
	83	+ * }});
	84	+ * executor.execute(future);}</pre>
	85	+ *
	86	+ * <p>Memory consistency effects: Actions taken by the asynchronous computation
	87	+ * <a href="package-summary.html#MemoryVisibility"> <i>happen-before</i></a>
	88	+ * actions following the corresponding {@code Future.get()} in another thread.
	89	+ *
	90	+ * @see FutureTask
	91	+ * @see Executor
	92	+ * @since 1.5
	93	+ * @author Doug Lea
	94	+ * @param <V> The result type returned by this Future's <tt>get</tt> method
	95	+ */
	96	+public interface Future<V> {
	97	+
	98	+ /**
	99	+ * Attempts to cancel execution of this task. This attempt will
	100	+ * fail if the task has already completed, has already been cancelled,
	101	+ * or could not be cancelled for some other reason. If successful,
	102	+ * and this task has not started when <tt>cancel</tt> is called,
	103	+ * this task should never run. If the task has already started,
	104	+ * then the <tt>mayInterruptIfRunning</tt> parameter determines
	105	+ * whether the thread executing this task should be interrupted in
	106	+ * an attempt to stop the task.
	107	+ *
	108	+ * <p>After this method returns, subsequent calls to {@link #isDone} will
	109	+ * always return <tt>true</tt>. Subsequent calls to {@link #isCancelled}
	110	+ * will always return <tt>true</tt> if this method returned <tt>true</tt>.
	111	+ *
	112	+ * @param mayInterruptIfRunning <tt>true</tt> if the thread executing this
	113	+ * task should be interrupted; otherwise, in-progress tasks are allowed
	114	+ * to complete
	115	+ * @return <tt>false</tt> if the task could not be cancelled,
	116	+ * typically because it has already completed normally;
	117	+ * <tt>true</tt> otherwise
	118	+ */
	119	+ boolean cancel(boolean mayInterruptIfRunning);
	120	+
	121	+ /**
	122	+ * Returns <tt>true</tt> if this task was cancelled before it completed
	123	+ * normally.
	124	+ *
	125	+ * @return <tt>true</tt> if this task was cancelled before it completed
	126	+ */
	127	+ boolean isCancelled();
	128	+
	129	+ /**
	130	+ * Returns <tt>true</tt> if this task completed.
	131	+ *
	132	+ * Completion may be due to normal termination, an exception, or
	133	+ * cancellation -- in all of these cases, this method will return
	134	+ * <tt>true</tt>.
	135	+ *
	136	+ * @return <tt>true</tt> if this task completed
	137	+ */
	138	+ boolean isDone();
	139	+
	140	+ /**
	141	+ * Waits if necessary for the computation to complete, and then
	142	+ * retrieves its result.
	143	+ *
	144	+ * @return the computed result
	145	+ * @throws CancellationException if the computation was cancelled
	146	+ * @throws ExecutionException if the computation threw an
	147	+ * exception
	148	+ * @throws InterruptedException if the current thread was interrupted
	149	+ * while waiting
	150	+ */
	151	+ V get() throws InterruptedException, ExecutionException;
	152	+
	153	+ /**
	154	+ * Waits if necessary for at most the given time for the computation
	155	+ * to complete, and then retrieves its result, if available.
	156	+ *
	157	+ * @param timeout the maximum time to wait
	158	+ * @param unit the time unit of the timeout argument
	159	+ * @return the computed result
	160	+ * @throws CancellationException if the computation was cancelled
	161	+ * @throws ExecutionException if the computation threw an
	162	+ * exception
	163	+ * @throws InterruptedException if the current thread was interrupted
	164	+ * while waiting
	165	+ * @throws TimeoutException if the wait timed out
	166	+ */
	167	+ V get(long timeout, TimeUnit unit)
	168	+ throws InterruptedException, ExecutionException, TimeoutException;
	169	+}