| 47 |
|
* these methods. There are no guarantees about the order of |
| 48 |
|
* processing completions unless constrained by these methods. |
| 49 |
|
* |
| 50 |
+ |
* <p>Since (unlike {@link FutureTask}) this class has no direct |
| 51 |
+ |
* control over the computation that causes it to be completed, |
| 52 |
+ |
* cancellation is treated as just another form of exceptional completion. |
| 53 |
+ |
* Method {@link #cancel cancel} has the same effect as |
| 54 |
+ |
* {@code completeExceptionally(new CancellationException())}. |
| 55 |
+ |
* |
| 56 |
|
* <p>Upon exceptional completion (including cancellation), or when a |
| 57 |
< |
* completion entails computation, and it terminates abruptly with an |
| 58 |
< |
* (unchecked) exception or error, then further completions act as |
| 59 |
< |
* {@code completeExceptionally} with a {@link CompletionException} |
| 60 |
< |
* holding that exception as its cause. If a CompletableFuture |
| 61 |
< |
* completes exceptionally, and is not followed by a {@link |
| 62 |
< |
* #exceptionally} or {@link #handle} completion, then all of its |
| 63 |
< |
* dependents (and their dependents) also complete exceptionally with |
| 64 |
< |
* CompletionExceptions holding the ultimate cause. In case of a |
| 65 |
< |
* CompletionException, methods {@link #get()} and {@link #get(long, |
| 66 |
< |
* TimeUnit)} throw an {@link ExecutionException} with the same cause |
| 67 |
< |
* as would be held in the corresponding CompletionException. However, |
| 68 |
< |
* in these cases, methods {@link #join()} and {@link #getNow} throw |
| 69 |
< |
* the CompletionException, which simplifies usage. |
| 57 |
> |
* completion entails an additional computation which terminates |
| 58 |
> |
* abruptly with an (unchecked) exception or error, then all of their |
| 59 |
> |
* dependent completions (and their dependents in turn) generally act |
| 60 |
> |
* as {@code completeExceptionally} with a {@link CompletionException} |
| 61 |
> |
* holding that exception as its cause. However, the {@link |
| 62 |
> |
* #exceptionally exceptionally} and {@link #handle handle} |
| 63 |
> |
* completions <em>are</em> able to handle exceptional completions of |
| 64 |
> |
* the CompletableFutures they depend on. |
| 65 |
> |
* |
| 66 |
> |
* <p>In case of exceptional completion with a CompletionException, |
| 67 |
> |
* methods {@link #get()} and {@link #get(long, TimeUnit)} throw an |
| 68 |
> |
* {@link ExecutionException} with the same cause as held in the |
| 69 |
> |
* corresponding CompletionException. However, in these cases, |
| 70 |
> |
* methods {@link #join()} and {@link #getNow} throw the |
| 71 |
> |
* CompletionException, which simplifies usage. |
| 72 |
|
* |
| 73 |
|
* <p>CompletableFutures themselves do not execute asynchronously. |
| 74 |
|
* However, the {@code async} methods provide commonly useful ways to |
| 114 |
|
* extends AtomicInteger so callers can claim the action via |
| 115 |
|
* compareAndSet(0, 1). The Completion.run methods are all |
| 116 |
|
* written a boringly similar uniform way (that sometimes includes |
| 117 |
< |
* unnecessary-looking checks, kept to maintain uniformity). There |
| 118 |
< |
* are enough dimensions upon which they differ that attempts to |
| 119 |
< |
* factor commonalities while maintaining efficiency require more |
| 120 |
< |
* lines of code than they would save. |
| 117 |
> |
* unnecessary-looking checks, kept to maintain uniformity). |
| 118 |
> |
* There are enough dimensions upon which they differ that |
| 119 |
> |
* attempts to factor commonalities while maintaining efficiency |
| 120 |
> |
* require more lines of code than they would save. |
| 121 |
|
* |
| 122 |
|
* 4. The exported then/and/or methods do support a bit of |
| 123 |
|
* factoring (see doThenApply etc). They must cope with the |
| 1492 |
|
* |
| 1493 |
|
* @return the result value |
| 1494 |
|
* @throws CancellationException if the computation was cancelled |
| 1495 |
< |
* @throws CompletionException if a completion computation threw |
| 1496 |
< |
* an exception |
| 1495 |
> |
* @throws CompletionException if this future completed |
| 1496 |
> |
* exceptionally or a completion computation threw an exception |
| 1497 |
|
*/ |
| 1498 |
|
public T join() { |
| 1499 |
|
Object r; Throwable ex; |
| 1519 |
|
* @param valueIfAbsent the value to return if not completed |
| 1520 |
|
* @return the result value, if completed, else the given valueIfAbsent |
| 1521 |
|
* @throws CancellationException if the computation was cancelled |
| 1522 |
< |
* @throws CompletionException if a completion computation threw |
| 1523 |
< |
* an exception |
| 1522 |
> |
* @throws CompletionException if this future completed |
| 1523 |
> |
* exceptionally or a completion computation threw an exception |
| 1524 |
|
*/ |
| 1525 |
|
public T getNow(T valueIfAbsent) { |
| 1526 |
|
Object r; Throwable ex; |
