| 141 |
|
/** |
| 142 |
|
* Table of exceptions thrown by tasks, to enable reporting by |
| 143 |
|
* callers. Because exceptions are rare, we don't directly keep |
| 144 |
< |
* them with task objects, but instead us a weak ref table. Note |
| 144 |
> |
* them with task objects, but instead use a weak ref table. Note |
| 145 |
|
* that cancellation exceptions don't appear in the table, but are |
| 146 |
|
* instead recorded as status values. |
| 147 |
< |
* Todo: Use ConcurrentReferenceHashMap |
| 147 |
> |
* TODO: Use ConcurrentReferenceHashMap |
| 148 |
|
*/ |
| 149 |
|
static final Map<ForkJoinTask<?>, Throwable> exceptionMap = |
| 150 |
|
Collections.synchronizedMap |
| 153 |
|
// within-package utilities |
| 154 |
|
|
| 155 |
|
/** |
| 156 |
< |
* Get current worker thread, or null if not a worker thread |
| 156 |
> |
* Gets current worker thread, or null if not a worker thread. |
| 157 |
|
*/ |
| 158 |
|
static ForkJoinWorkerThread getWorker() { |
| 159 |
|
Thread t = Thread.currentThread(); |
| 176 |
|
// Setting completion status |
| 177 |
|
|
| 178 |
|
/** |
| 179 |
< |
* Mark completion and wake up threads waiting to join this task. |
| 179 |
> |
* Marks completion and wakes up threads waiting to join this task. |
| 180 |
> |
* |
| 181 |
|
* @param completion one of NORMAL, CANCELLED, EXCEPTIONAL |
| 182 |
|
*/ |
| 183 |
|
final void setCompletion(int completion) { |
| 256 |
|
/** |
| 257 |
|
* Sets status to indicate there is joiner, then waits for join, |
| 258 |
|
* surrounded with pool notifications. |
| 259 |
+ |
* |
| 260 |
|
* @return status upon exit |
| 261 |
|
*/ |
| 262 |
|
private int awaitDone(ForkJoinWorkerThread w, boolean maintainParallelism) { |
| 299 |
|
} |
| 300 |
|
|
| 301 |
|
/** |
| 302 |
< |
* Notify pool that thread is unblocked. Called by signalled |
| 302 |
> |
* Notifies pool that thread is unblocked. Called by signalled |
| 303 |
|
* threads when woken by non-FJ threads (which is atypical). |
| 304 |
|
*/ |
| 305 |
|
private void adjustPoolCountsOnUnblock(ForkJoinPool pool) { |
| 310 |
|
} |
| 311 |
|
|
| 312 |
|
/** |
| 313 |
< |
* Notify pool to adjust counts on cancelled or timed out wait |
| 313 |
> |
* Notifies pool to adjust counts on cancelled or timed out wait. |
| 314 |
|
*/ |
| 315 |
|
private void adjustPoolCountsOnCancelledWait(ForkJoinPool pool) { |
| 316 |
|
if (pool != null) { |
| 325 |
|
} |
| 326 |
|
|
| 327 |
|
/** |
| 328 |
< |
* Handle interruptions during waits. |
| 328 |
> |
* Handles interruptions during waits. |
| 329 |
|
*/ |
| 330 |
|
private void onInterruptedWait() { |
| 331 |
|
ForkJoinWorkerThread w = getWorker(); |
| 344 |
|
} |
| 345 |
|
|
| 346 |
|
/** |
| 347 |
< |
* Throws the exception associated with status s; |
| 347 |
> |
* Throws the exception associated with status s. |
| 348 |
> |
* |
| 349 |
|
* @throws the exception |
| 350 |
|
*/ |
| 351 |
|
private void reportException(int s) { |
| 358 |
|
} |
| 359 |
|
|
| 360 |
|
/** |
| 361 |
< |
* Returns result or throws exception using j.u.c.Future conventions |
| 361 |
> |
* Returns result or throws exception using j.u.c.Future conventions. |
| 362 |
|
* Only call when isDone known to be true. |
| 363 |
|
*/ |
| 364 |
|
private V reportFutureResult() |
| 378 |
|
|
| 379 |
|
/** |
| 380 |
|
* Returns result or throws exception using j.u.c.Future conventions |
| 381 |
< |
* with timeouts |
| 381 |
> |
* with timeouts. |
| 382 |
|
*/ |
| 383 |
|
private V reportTimedFutureResult() |
| 384 |
|
throws InterruptedException, ExecutionException, TimeoutException { |
| 399 |
|
|
| 400 |
|
/** |
| 401 |
|
* Calls exec, recording completion, and rethrowing exception if |
| 402 |
< |
* encountered. Caller should normally check status before calling |
| 402 |
> |
* encountered. Caller should normally check status before calling. |
| 403 |
> |
* |
| 404 |
|
* @return true if completed normally |
| 405 |
|
*/ |
| 406 |
|
private boolean tryExec() { |
| 418 |
|
|
| 419 |
|
/** |
| 420 |
|
* Main execution method used by worker threads. Invokes |
| 421 |
< |
* base computation unless already complete |
| 421 |
> |
* base computation unless already complete. |
| 422 |
|
*/ |
| 423 |
|
final void quietlyExec() { |
| 424 |
|
if (status >= 0) { |
| 434 |
|
} |
| 435 |
|
|
| 436 |
|
/** |
| 437 |
< |
* Calls exec, recording but not rethrowing exception |
| 438 |
< |
* Caller should normally check status before calling |
| 437 |
> |
* Calls exec(), recording but not rethrowing exception. |
| 438 |
> |
* Caller should normally check status before calling. |
| 439 |
> |
* |
| 440 |
|
* @return true if completed normally |
| 441 |
|
*/ |
| 442 |
|
private boolean tryQuietlyInvoke() { |
| 452 |
|
} |
| 453 |
|
|
| 454 |
|
/** |
| 455 |
< |
* Cancel, ignoring any exceptions it throws |
| 455 |
> |
* Cancels, ignoring any exceptions it throws. |
| 456 |
|
*/ |
| 457 |
|
final void cancelIgnoringExceptions() { |
| 458 |
|
try { |
| 504 |
|
/** |
| 505 |
|
* Commences performing this task, awaits its completion if |
| 506 |
|
* necessary, and return its result. |
| 507 |
+ |
* |
| 508 |
|
* @throws Throwable (a RuntimeException, Error, or unchecked |
| 509 |
< |
* exception) if the underlying computation did so. |
| 509 |
> |
* exception) if the underlying computation did so |
| 510 |
|
* @return the computed result |
| 511 |
|
*/ |
| 512 |
|
public final V invoke() { |
| 522 |
|
* invoked only from within ForkJoinTask computations. Attempts to |
| 523 |
|
* invoke in other contexts result in exceptions or errors |
| 524 |
|
* possibly including ClassCastException. |
| 525 |
+ |
* |
| 526 |
|
* @param t1 one task |
| 527 |
|
* @param t2 the other task |
| 528 |
|
* @throws NullPointerException if t1 or t2 are null |
| 529 |
< |
* @throws RuntimeException or Error if either task did so. |
| 529 |
> |
* @throws RuntimeException or Error if either task did so |
| 530 |
|
*/ |
| 531 |
|
public static void invokeAll(ForkJoinTask<?>t1, ForkJoinTask<?> t2) { |
| 532 |
|
t2.fork(); |
| 540 |
|
* may be cancelled. This method may be invoked only from within |
| 541 |
|
* ForkJoinTask computations. Attempts to invoke in other contexts |
| 542 |
|
* result in exceptions or errors possibly including ClassCastException. |
| 543 |
+ |
* |
| 544 |
|
* @param tasks the array of tasks |
| 545 |
< |
* @throws NullPointerException if tasks or any element are null. |
| 546 |
< |
* @throws RuntimeException or Error if any task did so. |
| 545 |
> |
* @throws NullPointerException if tasks or any element are null |
| 546 |
> |
* @throws RuntimeException or Error if any task did so |
| 547 |
|
*/ |
| 548 |
|
public static void invokeAll(ForkJoinTask<?>... tasks) { |
| 549 |
|
Throwable ex = null; |
| 585 |
|
* may be invoked only from within ForkJoinTask |
| 586 |
|
* computations. Attempts to invoke in other contexts result in |
| 587 |
|
* exceptions or errors possibly including ClassCastException. |
| 588 |
+ |
* |
| 589 |
|
* @param tasks the collection of tasks |
| 590 |
< |
* @throws NullPointerException if tasks or any element are null. |
| 591 |
< |
* @throws RuntimeException or Error if any task did so. |
| 590 |
> |
* @throws NullPointerException if tasks or any element are null |
| 591 |
> |
* @throws RuntimeException or Error if any task did so |
| 592 |
|
*/ |
| 593 |
|
public static void invokeAll(Collection<? extends ForkJoinTask<?>> tasks) { |
| 594 |
|
if (!(tasks instanceof List)) { |
| 632 |
|
/** |
| 633 |
|
* Returns true if the computation performed by this task has |
| 634 |
|
* completed (or has been cancelled). |
| 635 |
+ |
* |
| 636 |
|
* @return true if this computation has completed |
| 637 |
|
*/ |
| 638 |
|
public final boolean isDone() { |
| 641 |
|
|
| 642 |
|
/** |
| 643 |
|
* Returns true if this task was cancelled. |
| 644 |
+ |
* |
| 645 |
|
* @return true if this task was cancelled |
| 646 |
|
*/ |
| 647 |
|
public final boolean isCancelled() { |
| 681 |
|
} |
| 682 |
|
|
| 683 |
|
/** |
| 684 |
< |
* Returns true if this task threw an exception or was cancelled |
| 684 |
> |
* Returns true if this task threw an exception or was cancelled. |
| 685 |
> |
* |
| 686 |
|
* @return true if this task threw an exception or was cancelled |
| 687 |
|
*/ |
| 688 |
|
public final boolean isCompletedAbnormally() { |
| 693 |
|
* Returns the exception thrown by the base computation, or a |
| 694 |
|
* CancellationException if cancelled, or null if none or if the |
| 695 |
|
* method has not yet completed. |
| 696 |
+ |
* |
| 697 |
|
* @return the exception, or null if none |
| 698 |
|
*/ |
| 699 |
|
public final Throwable getException() { |
| 735 |
|
* overridable, but overridden versions must invoke {@code super} |
| 736 |
|
* implementation to maintain guarantees. |
| 737 |
|
* |
| 738 |
< |
* @param value the result value for this task. |
| 738 |
> |
* @param value the result value for this task |
| 739 |
|
*/ |
| 740 |
|
public void complete(V value) { |
| 741 |
|
try { |
| 772 |
|
* tasks). This method may be invoked only from within |
| 773 |
|
* ForkJoinTask computations. Attempts to invoke in other contexts |
| 774 |
|
* result in exceptions or errors possibly including ClassCastException. |
| 775 |
+ |
* |
| 776 |
|
* @return the computed result |
| 777 |
|
*/ |
| 778 |
|
public final V helpJoin() { |
| 853 |
|
/** |
| 854 |
|
* Returns the pool hosting the current task execution, or null |
| 855 |
|
* if this task is executing outside of any pool. |
| 856 |
< |
* @return the pool, or null if none. |
| 856 |
> |
* |
| 857 |
> |
* @return the pool, or null if none |
| 858 |
|
*/ |
| 859 |
|
public static ForkJoinPool getPool() { |
| 860 |
|
Thread t = Thread.currentThread(); |
| 871 |
|
* were not, stolen. This method may be invoked only from within |
| 872 |
|
* ForkJoinTask computations. Attempts to invoke in other contexts |
| 873 |
|
* result in exceptions or errors possibly including ClassCastException. |
| 874 |
+ |
* |
| 875 |
|
* @return true if unforked |
| 876 |
|
*/ |
| 877 |
|
public boolean tryUnfork() { |
| 883 |
|
* forked by the current worker thread but not yet executed. This |
| 884 |
|
* value may be useful for heuristic decisions about whether to |
| 885 |
|
* fork other tasks. |
| 886 |
+ |
* |
| 887 |
|
* @return the number of tasks |
| 888 |
|
*/ |
| 889 |
|
public static int getQueuedTaskCount() { |
| 892 |
|
} |
| 893 |
|
|
| 894 |
|
/** |
| 895 |
< |
* Returns a estimate of how many more locally queued tasks are |
| 895 |
> |
* Returns an estimate of how many more locally queued tasks are |
| 896 |
|
* held by the current worker thread than there are other worker |
| 897 |
|
* threads that might steal them. This value may be useful for |
| 898 |
|
* heuristic decisions about whether to fork other tasks. In many |
| 900 |
|
* aim to maintain a small constant surplus (for example, 3) of |
| 901 |
|
* tasks, and to process computations locally if this threshold is |
| 902 |
|
* exceeded. |
| 903 |
+ |
* |
| 904 |
|
* @return the surplus number of tasks, which may be negative |
| 905 |
|
*/ |
| 906 |
|
public static int getSurplusQueuedTaskCount() { |
| 917 |
|
* aid debugging, as well as to support extensions. Its use in any |
| 918 |
|
* other context is discouraged. |
| 919 |
|
* |
| 920 |
< |
* @return the result, or null if not completed. |
| 920 |
> |
* @return the result, or null if not completed |
| 921 |
|
*/ |
| 922 |
|
public abstract V getRawResult(); |
| 923 |
|
|
| 938 |
|
* asynchronous actions that require explicit invocations of |
| 939 |
|
* {@code complete} to become joinable. It may throw exceptions |
| 940 |
|
* to indicate abnormal exit. |
| 941 |
+ |
* |
| 942 |
|
* @return true if completed normally |
| 943 |
|
* @throws Error or RuntimeException if encountered during computation |
| 944 |
|
*/ |
| 1003 |
|
* Save the state to a stream. |
| 1004 |
|
* |
| 1005 |
|
* @serialData the current run status and the exception thrown |
| 1006 |
< |
* during execution, or null if none. |
| 1006 |
> |
* during execution, or null if none |
| 1007 |
|
* @param s the stream |
| 1008 |
|
*/ |
| 1009 |
|
private void writeObject(java.io.ObjectOutputStream s) |
| 1014 |
|
|
| 1015 |
|
/** |
| 1016 |
|
* Reconstitute the instance from a stream. |
| 1017 |
+ |
* |
| 1018 |
|
* @param s the stream |
| 1019 |
|
*/ |
| 1020 |
|
private void readObject(java.io.ObjectInputStream s) |
