| 107 |
|
* in general sensible to serialize tasks only before or after, but |
| 108 |
|
* not during execution. Serialization is not relied on during |
| 109 |
|
* execution itself. |
| 110 |
+ |
* |
| 111 |
+ |
* @since 1.7 |
| 112 |
+ |
* @author Doug Lea |
| 113 |
|
*/ |
| 114 |
|
public abstract class ForkJoinTask<V> implements Future<V>, Serializable { |
| 115 |
|
|
| 144 |
|
/** |
| 145 |
|
* Table of exceptions thrown by tasks, to enable reporting by |
| 146 |
|
* callers. Because exceptions are rare, we don't directly keep |
| 147 |
< |
* them with task objects, but instead us a weak ref table. Note |
| 147 |
> |
* them with task objects, but instead use a weak ref table. Note |
| 148 |
|
* that cancellation exceptions don't appear in the table, but are |
| 149 |
|
* instead recorded as status values. |
| 150 |
< |
* Todo: Use ConcurrentReferenceHashMap |
| 150 |
> |
* TODO: Use ConcurrentReferenceHashMap |
| 151 |
|
*/ |
| 152 |
|
static final Map<ForkJoinTask<?>, Throwable> exceptionMap = |
| 153 |
|
Collections.synchronizedMap |
| 156 |
|
// within-package utilities |
| 157 |
|
|
| 158 |
|
/** |
| 159 |
< |
* Get current worker thread, or null if not a worker thread |
| 159 |
> |
* Gets current worker thread, or null if not a worker thread. |
| 160 |
|
*/ |
| 161 |
|
static ForkJoinWorkerThread getWorker() { |
| 162 |
|
Thread t = Thread.currentThread(); |
| 165 |
|
} |
| 166 |
|
|
| 167 |
|
final boolean casStatus(int cmp, int val) { |
| 168 |
< |
return _unsafe.compareAndSwapInt(this, statusOffset, cmp, val); |
| 168 |
> |
return UNSAFE.compareAndSwapInt(this, statusOffset, cmp, val); |
| 169 |
|
} |
| 170 |
|
|
| 171 |
|
/** |
| 173 |
|
*/ |
| 174 |
|
static void rethrowException(Throwable ex) { |
| 175 |
|
if (ex != null) |
| 176 |
< |
_unsafe.throwException(ex); |
| 176 |
> |
UNSAFE.throwException(ex); |
| 177 |
|
} |
| 178 |
|
|
| 179 |
|
// Setting completion status |
| 180 |
|
|
| 181 |
|
/** |
| 182 |
< |
* Mark completion and wake up threads waiting to join this task. |
| 182 |
> |
* Marks completion and wakes up threads waiting to join this task. |
| 183 |
> |
* |
| 184 |
|
* @param completion one of NORMAL, CANCELLED, EXCEPTIONAL |
| 185 |
|
*/ |
| 186 |
|
final void setCompletion(int completion) { |
| 216 |
|
final void setNormalCompletion() { |
| 217 |
|
// Try typical fast case -- single CAS, no signal, not already done. |
| 218 |
|
// Manually expand casStatus to improve chances of inlining it |
| 219 |
< |
if (!_unsafe.compareAndSwapInt(this, statusOffset, 0, NORMAL)) |
| 219 |
> |
if (!UNSAFE.compareAndSwapInt(this, statusOffset, 0, NORMAL)) |
| 220 |
|
setCompletion(NORMAL); |
| 221 |
|
} |
| 222 |
|
|
| 259 |
|
/** |
| 260 |
|
* Sets status to indicate there is joiner, then waits for join, |
| 261 |
|
* surrounded with pool notifications. |
| 262 |
+ |
* |
| 263 |
|
* @return status upon exit |
| 264 |
|
*/ |
| 265 |
|
private int awaitDone(ForkJoinWorkerThread w, boolean maintainParallelism) { |
| 302 |
|
} |
| 303 |
|
|
| 304 |
|
/** |
| 305 |
< |
* Notify pool that thread is unblocked. Called by signalled |
| 305 |
> |
* Notifies pool that thread is unblocked. Called by signalled |
| 306 |
|
* threads when woken by non-FJ threads (which is atypical). |
| 307 |
|
*/ |
| 308 |
|
private void adjustPoolCountsOnUnblock(ForkJoinPool pool) { |
| 313 |
|
} |
| 314 |
|
|
| 315 |
|
/** |
| 316 |
< |
* Notify pool to adjust counts on cancelled or timed out wait |
| 316 |
> |
* Notifies pool to adjust counts on cancelled or timed out wait. |
| 317 |
|
*/ |
| 318 |
|
private void adjustPoolCountsOnCancelledWait(ForkJoinPool pool) { |
| 319 |
|
if (pool != null) { |
| 328 |
|
} |
| 329 |
|
|
| 330 |
|
/** |
| 331 |
< |
* Handle interruptions during waits. |
| 331 |
> |
* Handles interruptions during waits. |
| 332 |
|
*/ |
| 333 |
|
private void onInterruptedWait() { |
| 334 |
|
ForkJoinWorkerThread w = getWorker(); |
| 347 |
|
} |
| 348 |
|
|
| 349 |
|
/** |
| 350 |
< |
* Throws the exception associated with status s; |
| 350 |
> |
* Throws the exception associated with status s. |
| 351 |
> |
* |
| 352 |
|
* @throws the exception |
| 353 |
|
*/ |
| 354 |
|
private void reportException(int s) { |
| 361 |
|
} |
| 362 |
|
|
| 363 |
|
/** |
| 364 |
< |
* Returns result or throws exception using j.u.c.Future conventions |
| 364 |
> |
* Returns result or throws exception using j.u.c.Future conventions. |
| 365 |
|
* Only call when isDone known to be true. |
| 366 |
|
*/ |
| 367 |
|
private V reportFutureResult() |
| 381 |
|
|
| 382 |
|
/** |
| 383 |
|
* Returns result or throws exception using j.u.c.Future conventions |
| 384 |
< |
* with timeouts |
| 384 |
> |
* with timeouts. |
| 385 |
|
*/ |
| 386 |
|
private V reportTimedFutureResult() |
| 387 |
|
throws InterruptedException, ExecutionException, TimeoutException { |
| 402 |
|
|
| 403 |
|
/** |
| 404 |
|
* Calls exec, recording completion, and rethrowing exception if |
| 405 |
< |
* encountered. Caller should normally check status before calling |
| 405 |
> |
* encountered. Caller should normally check status before calling. |
| 406 |
> |
* |
| 407 |
|
* @return true if completed normally |
| 408 |
|
*/ |
| 409 |
|
private boolean tryExec() { |
| 421 |
|
|
| 422 |
|
/** |
| 423 |
|
* Main execution method used by worker threads. Invokes |
| 424 |
< |
* base computation unless already complete |
| 424 |
> |
* base computation unless already complete. |
| 425 |
|
*/ |
| 426 |
|
final void quietlyExec() { |
| 427 |
|
if (status >= 0) { |
| 437 |
|
} |
| 438 |
|
|
| 439 |
|
/** |
| 440 |
< |
* Calls exec, recording but not rethrowing exception |
| 441 |
< |
* Caller should normally check status before calling |
| 440 |
> |
* Calls exec(), recording but not rethrowing exception. |
| 441 |
> |
* Caller should normally check status before calling. |
| 442 |
> |
* |
| 443 |
|
* @return true if completed normally |
| 444 |
|
*/ |
| 445 |
|
private boolean tryQuietlyInvoke() { |
| 455 |
|
} |
| 456 |
|
|
| 457 |
|
/** |
| 458 |
< |
* Cancel, ignoring any exceptions it throws |
| 458 |
> |
* Cancels, ignoring any exceptions it throws. |
| 459 |
|
*/ |
| 460 |
|
final void cancelIgnoringExceptions() { |
| 461 |
|
try { |
| 507 |
|
/** |
| 508 |
|
* Commences performing this task, awaits its completion if |
| 509 |
|
* necessary, and return its result. |
| 510 |
+ |
* |
| 511 |
|
* @throws Throwable (a RuntimeException, Error, or unchecked |
| 512 |
< |
* exception) if the underlying computation did so. |
| 512 |
> |
* exception) if the underlying computation did so |
| 513 |
|
* @return the computed result |
| 514 |
|
*/ |
| 515 |
|
public final V invoke() { |
| 525 |
|
* invoked only from within ForkJoinTask computations. Attempts to |
| 526 |
|
* invoke in other contexts result in exceptions or errors |
| 527 |
|
* possibly including ClassCastException. |
| 528 |
+ |
* |
| 529 |
|
* @param t1 one task |
| 530 |
|
* @param t2 the other task |
| 531 |
|
* @throws NullPointerException if t1 or t2 are null |
| 532 |
< |
* @throws RuntimeException or Error if either task did so. |
| 532 |
> |
* @throws RuntimeException or Error if either task did so |
| 533 |
|
*/ |
| 534 |
|
public static void invokeAll(ForkJoinTask<?>t1, ForkJoinTask<?> t2) { |
| 535 |
|
t2.fork(); |
| 543 |
|
* may be cancelled. This method may be invoked only from within |
| 544 |
|
* ForkJoinTask computations. Attempts to invoke in other contexts |
| 545 |
|
* result in exceptions or errors possibly including ClassCastException. |
| 546 |
+ |
* |
| 547 |
|
* @param tasks the array of tasks |
| 548 |
< |
* @throws NullPointerException if tasks or any element are null. |
| 549 |
< |
* @throws RuntimeException or Error if any task did so. |
| 548 |
> |
* @throws NullPointerException if tasks or any element are null |
| 549 |
> |
* @throws RuntimeException or Error if any task did so |
| 550 |
|
*/ |
| 551 |
|
public static void invokeAll(ForkJoinTask<?>... tasks) { |
| 552 |
|
Throwable ex = null; |
| 588 |
|
* may be invoked only from within ForkJoinTask |
| 589 |
|
* computations. Attempts to invoke in other contexts result in |
| 590 |
|
* exceptions or errors possibly including ClassCastException. |
| 591 |
+ |
* |
| 592 |
|
* @param tasks the collection of tasks |
| 593 |
< |
* @throws NullPointerException if tasks or any element are null. |
| 594 |
< |
* @throws RuntimeException or Error if any task did so. |
| 593 |
> |
* @throws NullPointerException if tasks or any element are null |
| 594 |
> |
* @throws RuntimeException or Error if any task did so |
| 595 |
|
*/ |
| 596 |
|
public static void invokeAll(Collection<? extends ForkJoinTask<?>> tasks) { |
| 597 |
|
if (!(tasks instanceof List)) { |
| 635 |
|
/** |
| 636 |
|
* Returns true if the computation performed by this task has |
| 637 |
|
* completed (or has been cancelled). |
| 638 |
+ |
* |
| 639 |
|
* @return true if this computation has completed |
| 640 |
|
*/ |
| 641 |
|
public final boolean isDone() { |
| 644 |
|
|
| 645 |
|
/** |
| 646 |
|
* Returns true if this task was cancelled. |
| 647 |
+ |
* |
| 648 |
|
* @return true if this task was cancelled |
| 649 |
|
*/ |
| 650 |
|
public final boolean isCancelled() { |
| 684 |
|
} |
| 685 |
|
|
| 686 |
|
/** |
| 687 |
< |
* Returns true if this task threw an exception or was cancelled |
| 687 |
> |
* Returns true if this task threw an exception or was cancelled. |
| 688 |
> |
* |
| 689 |
|
* @return true if this task threw an exception or was cancelled |
| 690 |
|
*/ |
| 691 |
|
public final boolean isCompletedAbnormally() { |
| 696 |
|
* Returns the exception thrown by the base computation, or a |
| 697 |
|
* CancellationException if cancelled, or null if none or if the |
| 698 |
|
* method has not yet completed. |
| 699 |
+ |
* |
| 700 |
|
* @return the exception, or null if none |
| 701 |
|
*/ |
| 702 |
|
public final Throwable getException() { |
| 738 |
|
* overridable, but overridden versions must invoke {@code super} |
| 739 |
|
* implementation to maintain guarantees. |
| 740 |
|
* |
| 741 |
< |
* @param value the result value for this task. |
| 741 |
> |
* @param value the result value for this task |
| 742 |
|
*/ |
| 743 |
|
public void complete(V value) { |
| 744 |
|
try { |
| 775 |
|
* tasks). This method may be invoked only from within |
| 776 |
|
* ForkJoinTask computations. Attempts to invoke in other contexts |
| 777 |
|
* result in exceptions or errors possibly including ClassCastException. |
| 778 |
+ |
* |
| 779 |
|
* @return the computed result |
| 780 |
|
*/ |
| 781 |
|
public final V helpJoin() { |
| 856 |
|
/** |
| 857 |
|
* Returns the pool hosting the current task execution, or null |
| 858 |
|
* if this task is executing outside of any pool. |
| 859 |
< |
* @return the pool, or null if none. |
| 859 |
> |
* |
| 860 |
> |
* @return the pool, or null if none |
| 861 |
|
*/ |
| 862 |
|
public static ForkJoinPool getPool() { |
| 863 |
|
Thread t = Thread.currentThread(); |
| 874 |
|
* were not, stolen. This method may be invoked only from within |
| 875 |
|
* ForkJoinTask computations. Attempts to invoke in other contexts |
| 876 |
|
* result in exceptions or errors possibly including ClassCastException. |
| 877 |
+ |
* |
| 878 |
|
* @return true if unforked |
| 879 |
|
*/ |
| 880 |
|
public boolean tryUnfork() { |
| 886 |
|
* forked by the current worker thread but not yet executed. This |
| 887 |
|
* value may be useful for heuristic decisions about whether to |
| 888 |
|
* fork other tasks. |
| 889 |
+ |
* |
| 890 |
|
* @return the number of tasks |
| 891 |
|
*/ |
| 892 |
|
public static int getQueuedTaskCount() { |
| 895 |
|
} |
| 896 |
|
|
| 897 |
|
/** |
| 898 |
< |
* Returns a estimate of how many more locally queued tasks are |
| 898 |
> |
* Returns an estimate of how many more locally queued tasks are |
| 899 |
|
* held by the current worker thread than there are other worker |
| 900 |
|
* threads that might steal them. This value may be useful for |
| 901 |
|
* heuristic decisions about whether to fork other tasks. In many |
| 903 |
|
* aim to maintain a small constant surplus (for example, 3) of |
| 904 |
|
* tasks, and to process computations locally if this threshold is |
| 905 |
|
* exceeded. |
| 906 |
+ |
* |
| 907 |
|
* @return the surplus number of tasks, which may be negative |
| 908 |
|
*/ |
| 909 |
|
public static int getSurplusQueuedTaskCount() { |
| 920 |
|
* aid debugging, as well as to support extensions. Its use in any |
| 921 |
|
* other context is discouraged. |
| 922 |
|
* |
| 923 |
< |
* @return the result, or null if not completed. |
| 923 |
> |
* @return the result, or null if not completed |
| 924 |
|
*/ |
| 925 |
|
public abstract V getRawResult(); |
| 926 |
|
|
| 941 |
|
* asynchronous actions that require explicit invocations of |
| 942 |
|
* {@code complete} to become joinable. It may throw exceptions |
| 943 |
|
* to indicate abnormal exit. |
| 944 |
+ |
* |
| 945 |
|
* @return true if completed normally |
| 946 |
|
* @throws Error or RuntimeException if encountered during computation |
| 947 |
|
*/ |
| 1006 |
|
* Save the state to a stream. |
| 1007 |
|
* |
| 1008 |
|
* @serialData the current run status and the exception thrown |
| 1009 |
< |
* during execution, or null if none. |
| 1009 |
> |
* during execution, or null if none |
| 1010 |
|
* @param s the stream |
| 1011 |
|
*/ |
| 1012 |
|
private void writeObject(java.io.ObjectOutputStream s) |
| 1017 |
|
|
| 1018 |
|
/** |
| 1019 |
|
* Reconstitute the instance from a stream. |
| 1020 |
+ |
* |
| 1021 |
|
* @param s the stream |
| 1022 |
|
*/ |
| 1023 |
|
private void readObject(java.io.ObjectInputStream s) |
| 1056 |
|
|
| 1057 |
|
private static long fieldOffset(String fieldName) |
| 1058 |
|
throws NoSuchFieldException { |
| 1059 |
< |
return _unsafe.objectFieldOffset |
| 1059 |
> |
return UNSAFE.objectFieldOffset |
| 1060 |
|
(ForkJoinTask.class.getDeclaredField(fieldName)); |
| 1061 |
|
} |
| 1062 |
|
|
| 1063 |
< |
static final Unsafe _unsafe; |
| 1063 |
> |
static final Unsafe UNSAFE; |
| 1064 |
|
static final long statusOffset; |
| 1065 |
|
|
| 1066 |
|
static { |
| 1067 |
|
try { |
| 1068 |
< |
_unsafe = getUnsafe(); |
| 1068 |
> |
UNSAFE = getUnsafe(); |
| 1069 |
|
statusOffset = fieldOffset("status"); |
| 1070 |
|
} catch (Throwable e) { |
| 1071 |
|
throw new RuntimeException("Could not initialize intrinsics", e); |
