110 |
|
* result in exceptions or errors, possibly including |
111 |
|
* {@code ClassCastException}. |
112 |
|
* |
113 |
+ |
* <p>Method {@link #join} and its variants are appropriate for use |
114 |
+ |
* only when completion dependencies are acyclic; that is, the |
115 |
+ |
* parallel computation can be described as a directed acyclic graph |
116 |
+ |
* (DAG). Otherwise, executions may encounter a form of deadlock as |
117 |
+ |
* tasks cyclically wait for each other. However, this framework |
118 |
+ |
* supports other methods and techniques (for example the use of |
119 |
+ |
* {@link Phaser}, {@link #helpQuiesce}, and {@link #complete}) that |
120 |
+ |
* may be of use in constructing custom subclasses for problems that |
121 |
+ |
* are not statically structured as DAGs. |
122 |
+ |
* |
123 |
|
* <p>Most base support methods are {@code final}, to prevent |
124 |
|
* overriding of implementations that are intrinsically tied to the |
125 |
|
* underlying lightweight task scheduling framework. Developers |
340 |
|
} |
341 |
|
|
342 |
|
/** |
343 |
< |
* Returns the result of the computation when it {@link #isDone is done}. |
344 |
< |
* This method differs from {@link #get()} in that |
343 |
> |
* Returns the result of the computation when it {@link #isDone is |
344 |
> |
* done}. This method differs from {@link #get()} in that |
345 |
|
* abnormal completion results in {@code RuntimeException} or |
346 |
< |
* {@code Error}, not {@code ExecutionException}. |
346 |
> |
* {@code Error}, not {@code ExecutionException}, and that |
347 |
> |
* interrupts of the calling thread do <em>not</em> cause the |
348 |
> |
* method to abruptly return by throwing {@code |
349 |
> |
* InterruptedException}. |
350 |
|
* |
351 |
|
* @return the computed result |
352 |
|
*/ |
388 |
|
* unprocessed. |
389 |
|
* |
390 |
|
* <p>This method may be invoked only from within {@code |
391 |
< |
* ForkJoinTask} computations (as may be determined using method |
391 |
> |
* ForkJoinPool} computations (as may be determined using method |
392 |
|
* {@link #inForkJoinPool}). Attempts to invoke in other contexts |
393 |
|
* result in exceptions or errors, possibly including {@code |
394 |
|
* ClassCastException}. |
416 |
|
* normally or exceptionally, or left unprocessed. |
417 |
|
* |
418 |
|
* <p>This method may be invoked only from within {@code |
419 |
< |
* ForkJoinTask} computations (as may be determined using method |
419 |
> |
* ForkJoinPool} computations (as may be determined using method |
420 |
|
* {@link #inForkJoinPool}). Attempts to invoke in other contexts |
421 |
|
* result in exceptions or errors, possibly including {@code |
422 |
|
* ClassCastException}. |
471 |
|
* unprocessed. |
472 |
|
* |
473 |
|
* <p>This method may be invoked only from within {@code |
474 |
< |
* ForkJoinTask} computations (as may be determined using method |
474 |
> |
* ForkJoinPool} computations (as may be determined using method |
475 |
|
* {@link #inForkJoinPool}). Attempts to invoke in other contexts |
476 |
|
* result in exceptions or errors, possibly including {@code |
477 |
|
* ClassCastException}. |
523 |
|
|
524 |
|
/** |
525 |
|
* Attempts to cancel execution of this task. This attempt will |
526 |
< |
* fail if the task has already completed, has already been |
527 |
< |
* cancelled, or could not be cancelled for some other reason. If |
528 |
< |
* successful, and this task has not started when cancel is |
529 |
< |
* called, execution of this task is suppressed, {@link |
530 |
< |
* #isCancelled} will report true, and {@link #join} will result |
531 |
< |
* in a {@code CancellationException} being thrown. |
526 |
> |
* fail if the task has already completed or could not be |
527 |
> |
* cancelled for some other reason. If successful, and this task |
528 |
> |
* has not started when {@code cancel} is called, execution of |
529 |
> |
* this task is suppressed. After this method returns |
530 |
> |
* successfully, unless there is an intervening call to {@link |
531 |
> |
* #reinitialize}, subsequent calls to {@link #isCancelled}, |
532 |
> |
* {@link #isDone}, and {@code cancel} will return {@code true} |
533 |
> |
* and calls to {@link #join} and related methods will result in |
534 |
> |
* {@code CancellationException}. |
535 |
|
* |
536 |
|
* <p>This method may be overridden in subclasses, but if so, must |
537 |
< |
* still ensure that these minimal properties hold. In particular, |
538 |
< |
* the {@code cancel} method itself must not throw exceptions. |
537 |
> |
* still ensure that these properties hold. In particular, the |
538 |
> |
* {@code cancel} method itself must not throw exceptions. |
539 |
|
* |
540 |
|
* <p>This method is designed to be invoked by <em>other</em> |
541 |
|
* tasks. To terminate the current task, you can just return or |
542 |
|
* throw an unchecked exception from its computation method, or |
543 |
|
* invoke {@link #completeExceptionally}. |
544 |
|
* |
545 |
< |
* @param mayInterruptIfRunning this value is ignored in the |
546 |
< |
* default implementation because tasks are not |
547 |
< |
* cancelled via interruption |
545 |
> |
* @param mayInterruptIfRunning this value has no effect in the |
546 |
> |
* default implementation because interrupts are not used to |
547 |
> |
* control cancellation. |
548 |
|
* |
549 |
|
* @return {@code true} if this task is now cancelled |
550 |
|
*/ |
829 |
|
* processed. |
830 |
|
* |
831 |
|
* <p>This method may be invoked only from within {@code |
832 |
< |
* ForkJoinTask} computations (as may be determined using method |
832 |
> |
* ForkJoinPool} computations (as may be determined using method |
833 |
|
* {@link #inForkJoinPool}). Attempts to invoke in other contexts |
834 |
|
* result in exceptions or errors, possibly including {@code |
835 |
|
* ClassCastException}. |
894 |
|
* were not, stolen. |
895 |
|
* |
896 |
|
* <p>This method may be invoked only from within {@code |
897 |
< |
* ForkJoinTask} computations (as may be determined using method |
897 |
> |
* ForkJoinPool} computations (as may be determined using method |
898 |
|
* {@link #inForkJoinPool}). Attempts to invoke in other contexts |
899 |
|
* result in exceptions or errors, possibly including {@code |
900 |
|
* ClassCastException}. |
913 |
|
* fork other tasks. |
914 |
|
* |
915 |
|
* <p>This method may be invoked only from within {@code |
916 |
< |
* ForkJoinTask} computations (as may be determined using method |
916 |
> |
* ForkJoinPool} computations (as may be determined using method |
917 |
|
* {@link #inForkJoinPool}). Attempts to invoke in other contexts |
918 |
|
* result in exceptions or errors, possibly including {@code |
919 |
|
* ClassCastException}. |
936 |
|
* exceeded. |
937 |
|
* |
938 |
|
* <p>This method may be invoked only from within {@code |
939 |
< |
* ForkJoinTask} computations (as may be determined using method |
939 |
> |
* ForkJoinPool} computations (as may be determined using method |
940 |
|
* {@link #inForkJoinPool}). Attempts to invoke in other contexts |
941 |
|
* result in exceptions or errors, possibly including {@code |
942 |
|
* ClassCastException}. |
994 |
|
* otherwise. |
995 |
|
* |
996 |
|
* <p>This method may be invoked only from within {@code |
997 |
< |
* ForkJoinTask} computations (as may be determined using method |
997 |
> |
* ForkJoinPool} computations (as may be determined using method |
998 |
|
* {@link #inForkJoinPool}). Attempts to invoke in other contexts |
999 |
|
* result in exceptions or errors, possibly including {@code |
1000 |
|
* ClassCastException}. |
1013 |
|
* be useful otherwise. |
1014 |
|
* |
1015 |
|
* <p>This method may be invoked only from within {@code |
1016 |
< |
* ForkJoinTask} computations (as may be determined using method |
1016 |
> |
* ForkJoinPool} computations (as may be determined using method |
1017 |
|
* {@link #inForkJoinPool}). Attempts to invoke in other contexts |
1018 |
|
* result in exceptions or errors, possibly including {@code |
1019 |
|
* ClassCastException}. |
1036 |
|
* otherwise. |
1037 |
|
* |
1038 |
|
* <p>This method may be invoked only from within {@code |
1039 |
< |
* ForkJoinTask} computations (as may be determined using method |
1039 |
> |
* ForkJoinPool} computations (as may be determined using method |
1040 |
|
* {@link #inForkJoinPool}). Attempts to invoke in other contexts |
1041 |
|
* result in exceptions or errors, possibly including {@code |
1042 |
|
* ClassCastException}. |