ViewVC Help

View File | Revision Log | Show Annotations | Download File | Root Listing

root/jsr166/jsr166/src/main/java/util/concurrent/CompletableFuture.java

Comparing jsr166/src/main/java/util/concurrent/CompletableFuture.java (file contents):
Revision 1.47 by jsr166, Wed Feb 6 20:41:34 2013 UTC vs.
Revision 1.48 by dl, Sun Feb 10 14:27:54 2013 UTC

#	Line 27 | Line 27 | import java.util.concurrent.locks.LockSu
27		* value and status), and may include dependent functions and actions
28		* that trigger upon its completion.
29		*
30	<	* <p>When two or more threads attempt to {@link #complete} or {@link
31	<	* #completeExceptionally} a CompletableFuture, only one of them
32	<	* succeeds.
30	>	* <p>When two or more threads attempt to {@link #complete}, {@link
31	>	* #completeExceptionally}, or {@link #cancel} a CompletableFuture,
32	>	* only one of them succeeds.
33		*
34		* <p>Methods are available for adding dependents based on Functions,
35		* Consumers, and Runnables. The appropriate form to use depends on
#	Line 44 | Line 44 | import java.util.concurrent.locks.LockSu
44		* these methods.  There are no guarantees about the order of
45		* processing completions unless constrained by these methods.
46		*
47	<	* <p>Upon exceptional completion, or when a completion entails
48	<	* computation, and it terminates abruptly with an (unchecked)
49	<	* exception or error, then further completions act as {@code
50	<	* completeExceptionally} with a {@link CompletionException} holding
51	<	* that exception as its cause.  If a CompletableFuture completes
52	<	* exceptionally, and is not followed by a {@link #exceptionally} or
53	<	* {@link #handle} completion, then all of its dependents (and their
54	<	* dependents) also complete exceptionally with CompletionExceptions
55	<	* holding the ultimate cause.  In case of a CompletionException,
56	<	* methods {@link #get()} and {@link #get(long, TimeUnit)} throw an
57	<	* {@link ExecutionException} with the same cause as would be held in
58	<	* the corresponding CompletionException. However, in these cases,
59	<	* methods {@link #join()} and {@link #getNow} throw the
60	<	* CompletionException, which simplifies usage especially within other
61	<	* completion functions.
47	>	* <p>Upon exceptional completion (including cancellation), or when a
48	>	* completion entails computation, and it terminates abruptly with an
49	>	* (unchecked) exception or error, then further completions act as
50	>	* {@code completeExceptionally} with a {@link CompletionException}
51	>	* holding that exception as its cause.  If a CompletableFuture
52	>	* completes exceptionally, and is not followed by a {@link
53	>	* #exceptionally} or {@link #handle} completion, then all of its
54	>	* dependents (and their dependents) also complete exceptionally with
55	>	* CompletionExceptions holding the ultimate cause.  In case of a
56	>	* CompletionException, methods {@link #get()} and {@link #get(long,
57	>	* TimeUnit)} throw an {@link ExecutionException} with the same cause
58	>	* as would be held in the corresponding CompletionException. However,
59	>	* in these cases, methods {@link #join()} and {@link #getNow} throw
60	>	* the CompletionException, which simplifies usage.
61		*
62		* <p>CompletableFutures themselves do not execute asynchronously.
63		* However, the {@code async} methods provide commonly useful ways to
#	Line 1410 | Line 1409 | public class CompletableFuture<T> implem
1409
1410		/**
1411		* Waits if necessary for the computation to complete, and then
1412	<	* retrieves its result.
1412	>	* returns its result.
1413		*
1414	<	* @return the computed result
1415	<	* @throws CancellationException if the computation was cancelled
1416	<	* @throws ExecutionException if the computation threw an
1418	<	* exception
1414	>	* @return the result value
1415	>	* @throws CancellationException if this future was cancelled
1416	>	* @throws ExecutionException if this future completed exceptionally
1417		* @throws InterruptedException if the current thread was interrupted
1418		* while waiting
1419		*/
#	Line 1439 | Line 1437 | public class CompletableFuture<T> implem
1437
1438		/**
1439		* Waits if necessary for at most the given time for completion,
1440	<	* and then retrieves its result, if available.
1440	>	* and then returns its result, if available.
1441		*
1442		* @param timeout the maximum time to wait
1443		* @param unit the time unit of the timeout argument
1444	<	* @return the computed result
1445	<	* @throws CancellationException if the computation was cancelled
1446	<	* @throws ExecutionException if the computation threw an
1449	<	* exception
1444	>	* @return the result value
1445	>	* @throws CancellationException if this future was cancelled
1446	>	* @throws ExecutionException if this future completed exceptionally
1447		* @throws InterruptedException if the current thread was interrupted
1448		* while waiting
1449		* @throws TimeoutException if the wait timed out
#	Line 1591 | Line 1588 | public class CompletableFuture<T> implem
1588		* the returned CompletableFuture
1589		* @return the new CompletableFuture
1590		*/
1591	<	public <U> CompletableFuture<U> thenApplyAsync(Function<? super T,? extends U> fn) {
1591	>	public <U> CompletableFuture<U> thenApplyAsync
1592	>	(Function<? super T,? extends U> fn) {
1593		return doThenApply(fn, ForkJoinPool.commonPool());
1594		}
1595
#	Line 1608 | Line 1606 | public class CompletableFuture<T> implem
1606		* @param executor the executor to use for asynchronous execution
1607		* @return the new CompletableFuture
1608		*/
1609	<	public <U> CompletableFuture<U> thenApplyAsync(Function<? super T,? extends U> fn,
1610	<	Executor executor) {
1609	>	public <U> CompletableFuture<U> thenApplyAsync
1610	>	(Function<? super T,? extends U> fn,
1611	>	Executor executor) {
1612		if (executor == null) throw new NullPointerException();
1613		return doThenApply(fn, executor);
1614		}
1615
1616	<	private <U> CompletableFuture<U> doThenApply(Function<? super T,? extends U> fn,
1617	<	Executor e) {
1616	>	private <U> CompletableFuture<U> doThenApply
1617	>	(Function<? super T,? extends U> fn,
1618	>	Executor e) {
1619		if (fn == null) throw new NullPointerException();
1620		CompletableFuture<U> dst = new CompletableFuture<U>();
1621		ApplyCompletion<T,U> d = null;
#	Line 1853 | Line 1853 | public class CompletableFuture<T> implem
1853		* the returned CompletableFuture
1854		* @return the new CompletableFuture
1855		*/
1856	<	public <U,V> CompletableFuture<V> thenCombine(CompletableFuture<? extends U> other,
1857	<	BiFunction<? super T,? super U,? extends V> fn) {
1856	>	public <U,V> CompletableFuture<V> thenCombine
1857	>	(CompletableFuture<? extends U> other,
1858	>	BiFunction<? super T,? super U,? extends V> fn) {
1859		return doThenBiApply(other, fn, null);
1860		}
1861
#	Line 1872 | Line 1873 | public class CompletableFuture<T> implem
1873		* the returned CompletableFuture
1874		* @return the new CompletableFuture
1875		*/
1876	<	public <U,V> CompletableFuture<V> thenCombineAsync(CompletableFuture<? extends U> other,
1877	<	BiFunction<? super T,? super U,? extends V> fn) {
1876	>	public <U,V> CompletableFuture<V> thenCombineAsync
1877	>	(CompletableFuture<? extends U> other,
1878	>	BiFunction<? super T,? super U,? extends V> fn) {
1879		return doThenBiApply(other, fn, ForkJoinPool.commonPool());
1880		}
1881
#	Line 1893 | Line 1895 | public class CompletableFuture<T> implem
1895		* @return the new CompletableFuture
1896		*/
1897
1898	<	public <U,V> CompletableFuture<V> thenCombineAsync(CompletableFuture<? extends U> other,
1899	<	BiFunction<? super T,? super U,? extends V> fn,
1900	<	Executor executor) {
1898	>	public <U,V> CompletableFuture<V> thenCombineAsync
1899	>	(CompletableFuture<? extends U> other,
1900	>	BiFunction<? super T,? super U,? extends V> fn,
1901	>	Executor executor) {
1902		if (executor == null) throw new NullPointerException();
1903		return doThenBiApply(other, fn, executor);
1904		}
1905
1906	<	private <U,V> CompletableFuture<V> doThenBiApply(CompletableFuture<? extends U> other,
1907	<	BiFunction<? super T,? super U,? extends V> fn,
1908	<	Executor e) {
1906	>	private <U,V> CompletableFuture<V> doThenBiApply
1907	>	(CompletableFuture<? extends U> other,
1908	>	BiFunction<? super T,? super U,? extends V> fn,
1909	>	Executor e) {
1910		if (other == null || fn == null) throw new NullPointerException();
1911		CompletableFuture<V> dst = new CompletableFuture<V>();
1912		BiApplyCompletion<T,U,V> d = null;
#	Line 1980 | Line 1984 | public class CompletableFuture<T> implem
1984		* returned CompletableFuture
1985		* @return the new CompletableFuture
1986		*/
1987	<	public <U> CompletableFuture<Void> thenAcceptBoth(CompletableFuture<? extends U> other,
1988	<	BiConsumer<? super T, ? super U> block) {
1987	>	public <U> CompletableFuture<Void> thenAcceptBoth
1988	>	(CompletableFuture<? extends U> other,
1989	>	BiConsumer<? super T, ? super U> block) {
1990		return doThenBiAccept(other, block, null);
1991		}
1992
#	Line 1999 | Line 2004 | public class CompletableFuture<T> implem
2004		* returned CompletableFuture
2005		* @return the new CompletableFuture
2006		*/
2007	<	public <U> CompletableFuture<Void> thenAcceptBothAsync(CompletableFuture<? extends U> other,
2008	<	BiConsumer<? super T, ? super U> block) {
2007	>	public <U> CompletableFuture<Void> thenAcceptBothAsync
2008	>	(CompletableFuture<? extends U> other,
2009	>	BiConsumer<? super T, ? super U> block) {
2010		return doThenBiAccept(other, block, ForkJoinPool.commonPool());
2011		}
2012
#	Line 2018 | Line 2024 | public class CompletableFuture<T> implem
2024		* @param executor the executor to use for asynchronous execution
2025		* @return the new CompletableFuture
2026		*/
2027	<	public <U> CompletableFuture<Void> thenAcceptBothAsync(CompletableFuture<? extends U> other,
2028	<	BiConsumer<? super T, ? super U> block,
2029	<	Executor executor) {
2027	>	public <U> CompletableFuture<Void> thenAcceptBothAsync
2028	>	(CompletableFuture<? extends U> other,
2029	>	BiConsumer<? super T, ? super U> block,
2030	>	Executor executor) {
2031		if (executor == null) throw new NullPointerException();
2032		return doThenBiAccept(other, block, executor);
2033		}
2034
2035	<	private <U> CompletableFuture<Void> doThenBiAccept(CompletableFuture<? extends U> other,
2036	<	BiConsumer<? super T,? super U> fn,
2037	<	Executor e) {
2035	>	private <U> CompletableFuture<Void> doThenBiAccept
2036	>	(CompletableFuture<? extends U> other,
2037	>	BiConsumer<? super T,? super U> fn,
2038	>	Executor e) {
2039		if (other == null || fn == null) throw new NullPointerException();
2040		CompletableFuture<Void> dst = new CompletableFuture<Void>();
2041		BiAcceptCompletion<T,U> d = null;
#	Line 2215 | Line 2223 | public class CompletableFuture<T> implem
2223		* the returned CompletableFuture
2224		* @return the new CompletableFuture
2225		*/
2226	<	public <U> CompletableFuture<U> applyToEither(CompletableFuture<? extends T> other,
2227	<	Function<? super T, U> fn) {
2226	>	public <U> CompletableFuture<U> applyToEither
2227	>	(CompletableFuture<? extends T> other,
2228	>	Function<? super T, U> fn) {
2229		return doOrApply(other, fn, null);
2230		}
2231
#	Line 2236 | Line 2245 | public class CompletableFuture<T> implem
2245		* the returned CompletableFuture
2246		* @return the new CompletableFuture
2247		*/
2248	<	public <U> CompletableFuture<U> applyToEitherAsync(CompletableFuture<? extends T> other,
2249	<	Function<? super T, U> fn) {
2248	>	public <U> CompletableFuture<U> applyToEitherAsync
2249	>	(CompletableFuture<? extends T> other,
2250	>	Function<? super T, U> fn) {
2251		return doOrApply(other, fn, ForkJoinPool.commonPool());
2252		}
2253
#	Line 2258 | Line 2268 | public class CompletableFuture<T> implem
2268		* @param executor the executor to use for asynchronous execution
2269		* @return the new CompletableFuture
2270		*/
2271	<	public <U> CompletableFuture<U> applyToEitherAsync(CompletableFuture<? extends T> other,
2272	<	Function<? super T, U> fn,
2273	<	Executor executor) {
2271	>	public <U> CompletableFuture<U> applyToEitherAsync
2272	>	(CompletableFuture<? extends T> other,
2273	>	Function<? super T, U> fn,
2274	>	Executor executor) {
2275		if (executor == null) throw new NullPointerException();
2276		return doOrApply(other, fn, executor);
2277		}
2278
2279	<	private <U> CompletableFuture<U> doOrApply(CompletableFuture<? extends T> other,
2280	<	Function<? super T, U> fn,
2281	<	Executor e) {
2279	>	private <U> CompletableFuture<U> doOrApply
2280	>	(CompletableFuture<? extends T> other,
2281	>	Function<? super T, U> fn,
2282	>	Executor e) {
2283		if (other == null || fn == null) throw new NullPointerException();
2284		CompletableFuture<U> dst = new CompletableFuture<U>();
2285		OrApplyCompletion<T,U> d = null;
#	Line 2331 | Line 2343 | public class CompletableFuture<T> implem
2343		* returned CompletableFuture
2344		* @return the new CompletableFuture
2345		*/
2346	<	public CompletableFuture<Void> acceptEither(CompletableFuture<? extends T> other,
2347	<	Consumer<? super T> block) {
2346	>	public CompletableFuture<Void> acceptEither
2347	>	(CompletableFuture<? extends T> other,
2348	>	Consumer<? super T> block) {
2349		return doOrAccept(other, block, null);
2350		}
2351
#	Line 2352 | Line 2365 | public class CompletableFuture<T> implem
2365		* returned CompletableFuture
2366		* @return the new CompletableFuture
2367		*/
2368	<	public CompletableFuture<Void> acceptEitherAsync(CompletableFuture<? extends T> other,
2369	<	Consumer<? super T> block) {
2368	>	public CompletableFuture<Void> acceptEitherAsync
2369	>	(CompletableFuture<? extends T> other,
2370	>	Consumer<? super T> block) {
2371		return doOrAccept(other, block, ForkJoinPool.commonPool());
2372		}
2373
#	Line 2374 | Line 2388 | public class CompletableFuture<T> implem
2388		* @param executor the executor to use for asynchronous execution
2389		* @return the new CompletableFuture
2390		*/
2391	<	public CompletableFuture<Void> acceptEitherAsync(CompletableFuture<? extends T> other,
2392	<	Consumer<? super T> block,
2393	<	Executor executor) {
2391	>	public CompletableFuture<Void> acceptEitherAsync
2392	>	(CompletableFuture<? extends T> other,
2393	>	Consumer<? super T> block,
2394	>	Executor executor) {
2395		if (executor == null) throw new NullPointerException();
2396		return doOrAccept(other, block, executor);
2397		}
2398
2399	<	private CompletableFuture<Void> doOrAccept(CompletableFuture<? extends T> other,
2400	<	Consumer<? super T> fn,
2401	<	Executor e) {
2399	>	private CompletableFuture<Void> doOrAccept
2400	>	(CompletableFuture<? extends T> other,
2401	>	Consumer<? super T> fn,
2402	>	Executor e) {
2403		if (other == null || fn == null) throw new NullPointerException();
2404		CompletableFuture<Void> dst = new CompletableFuture<Void>();
2405		OrAcceptCompletion<T> d = null;
#	Line 2465 | Line 2481 | public class CompletableFuture<T> implem
2481		* returned CompletableFuture
2482		* @return the new CompletableFuture
2483		*/
2484	<	public CompletableFuture<Void> runAfterEitherAsync(CompletableFuture<?> other,
2485	<	Runnable action) {
2484	>	public CompletableFuture<Void> runAfterEitherAsync
2485	>	(CompletableFuture<?> other,
2486	>	Runnable action) {
2487		return doOrRun(other, action, ForkJoinPool.commonPool());
2488		}
2489
#	Line 2486 | Line 2503 | public class CompletableFuture<T> implem
2503		* @param executor the executor to use for asynchronous execution
2504		* @return the new CompletableFuture
2505		*/
2506	<	public CompletableFuture<Void> runAfterEitherAsync(CompletableFuture<?> other,
2507	<	Runnable action,
2508	<	Executor executor) {
2506	>	public CompletableFuture<Void> runAfterEitherAsync
2507	>	(CompletableFuture<?> other,
2508	>	Runnable action,
2509	>	Executor executor) {
2510		if (executor == null) throw new NullPointerException();
2511		return doOrRun(other, action, executor);
2512		}
#	Line 2550 | Line 2568 | public class CompletableFuture<T> implem
2568		* return if completed by the given function, or an exception
2569		* occurs
2570		*/
2571	<	public <U> CompletableFuture<U> thenCompose(Function<? super T,
2572	<	CompletableFuture<U>> fn) {
2571	>	public <U> CompletableFuture<U> thenCompose
2572	>	(Function<? super T, CompletableFuture<U>> fn) {
2573		return doCompose(fn, null);
2574		}
2575
#	Line 2568 | Line 2586 | public class CompletableFuture<T> implem
2586		* return if completed by the given function, or an exception
2587		* occurs
2588		*/
2589	<	public <U> CompletableFuture<U> thenComposeAsync(Function<? super T,
2590	<	CompletableFuture<U>> fn) {
2589	>	public <U> CompletableFuture<U> thenComposeAsync
2590	>	(Function<? super T, CompletableFuture<U>> fn) {
2591		return doCompose(fn, ForkJoinPool.commonPool());
2592		}
2593
#	Line 2587 | Line 2605 | public class CompletableFuture<T> implem
2605		* return if completed by the given function, or an exception
2606		* occurs
2607		*/
2608	<	public <U> CompletableFuture<U> thenComposeAsync(Function<? super T,
2609	<	CompletableFuture<U>> fn,
2610	<	Executor executor) {
2608	>	public <U> CompletableFuture<U> thenComposeAsync
2609	>	(Function<? super T, CompletableFuture<U>> fn,
2610	>	Executor executor) {
2611		if (executor == null) throw new NullPointerException();
2612		return doCompose(fn, executor);
2613		}
2614
2615	<	private <U> CompletableFuture<U> doCompose(Function<? super T,
2616	<	CompletableFuture<U>> fn,
2617	<	Executor e) {
2615	>	private <U> CompletableFuture<U> doCompose
2616	>	(Function<? super T, CompletableFuture<U>> fn,
2617	>	Executor e) {
2618		if (fn == null) throw new NullPointerException();
2619		CompletableFuture<U> dst = null;
2620		ComposeCompletion<T,U> d = null;
#	Line 2662 | Line 2680 | public class CompletableFuture<T> implem
2680		* exceptionally
2681		* @return the new CompletableFuture
2682		*/
2683	<	public CompletableFuture<T> exceptionally(Function<Throwable, ? extends T> fn) {
2683	>	public CompletableFuture<T> exceptionally
2684	>	(Function<Throwable, ? extends T> fn) {
2685		if (fn == null) throw new NullPointerException();
2686		CompletableFuture<T> dst = new CompletableFuture<T>();
2687		ExceptionCompletion<T> d = null;
#	Line 2710 | Line 2729 | public class CompletableFuture<T> implem
2729
2730		* @return the new CompletableFuture
2731		*/
2732	<	public <U> CompletableFuture<U> handle(BiFunction<? super T, Throwable, ? extends U> fn) {
2732	>	public <U> CompletableFuture<U> handle
2733	>	(BiFunction<? super T, Throwable, ? extends U> fn) {
2734		if (fn == null) throw new NullPointerException();
2735		CompletableFuture<U> dst = new CompletableFuture<U>();
2736		HandleCompletion<T,U> d = null;
#	Line 2767 | Line 2787 | public class CompletableFuture<T> implem
2787		* the component CompletableFutures are not reflected in the
2788		* returned CompletableFuture, but may be obtained by inspecting
2789		* them individually. If the number of components is zero, returns
2790	<	* a completed CompletableFuture.
2790	>	* a CompletableFuture completed with the value {@code null}.
2791		*
2792		* <p>Among the applications of this method is to await completion
2793		* of a set of independent CompletableFutures before continuing a
#	Line 2863 | Line 2883 | public class CompletableFuture<T> implem
2883		* Returns a new CompletableFuture that is completed when any of
2884		* the component CompletableFutures complete; with the same result if
2885		* it completed normally, otherwise exceptionally. If the number
2886	<	* of components is zero, returns a completed CompletableFuture.
2886	>	* of components is zero, returns an incomplete CompletableFuture.
2887		*
2888		* @param cfs the CompletableFutures
2889		* @return a CompletableFuture that is complete when any of the
#	Line 2879 | Line 2899 | public class CompletableFuture<T> implem
2899		CompletableFuture<?> dst = new CompletableFuture<Object>();
2900		CompletableFuture<?> f;
2901		if (len == 0)
2902	<	dst.result = NIL;
2902	>	; // skip
2903		else if ((f = cfs[0]) == null)
2904		throw new NullPointerException();
2905		else {
#	Line 2977 | Line 2997 | public class CompletableFuture<T> implem
2997		* @return {@code true} if this task is now cancelled
2998		*/
2999		public boolean cancel(boolean mayInterruptIfRunning) {
2980	–	Object r;
3000		boolean cancelled = (result == null) &&
3001		UNSAFE.compareAndSwapObject
3002		(this, RESULT, null, new AltResult(new CancellationException()));
3003		postComplete();
3004	<	return cancelled ||
2986	<	(((r = result) instanceof AltResult) &&
2987	<	(((AltResult)r).ex instanceof CancellationException));
3004	>	return cancelled || isCancelled();
3005		}
3006
3007		/**

Diff Legend

–	Removed lines
+	Added lines
<	Changed lines
>	Changed lines