--- jsr166/src/jsr166y/ForkJoinTask.java 2010/08/29 23:34:46 1.55 +++ jsr166/src/jsr166y/ForkJoinTask.java 2010/09/07 07:51:13 1.59 @@ -100,7 +100,7 @@ import java.util.WeakHashMap; * ForkJoinTasks (as may be determined using method {@link * #inForkJoinPool}). Attempts to invoke them in other contexts * result in exceptions or errors, possibly including - * ClassCastException. + * {@code ClassCastException}. * *

Most base support methods are {@code final}, to prevent * overriding of implementations that are intrinsically tied to the @@ -153,7 +153,7 @@ public abstract class ForkJoinTask im * single int to minimize footprint and to ensure atomicity (via * CAS). Status is initially zero, and takes on nonnegative * values until completed, upon which status holds value - * COMPLETED. CANCELLED, or EXCEPTIONAL. Tasks undergoing blocking + * NORMAL, CANCELLED, or EXCEPTIONAL. Tasks undergoing blocking * waits by other threads have the SIGNAL bit set. Completion of * a stolen task with SIGNAL set awakens any waiters via * notifyAll. Even though suboptimal for some purposes, we use @@ -205,7 +205,8 @@ public abstract class ForkJoinTask im } /** - * Record exception and set exceptional completion + * Records exception and sets exceptional completion. + * * @return status on exit */ private void setExceptionalCompletion(Throwable rex) { @@ -338,8 +339,9 @@ public abstract class ForkJoinTask im /** * Commences performing this task, awaits its completion if - * necessary, and return its result, or throws an (unchecked) - * exception if the underlying computation did so. + * necessary, and returns its result, or throws an (unchecked) + * {@code RuntimeException} or {@code Error} if the underlying + * computation did so. * * @return the computed result */ @@ -354,11 +356,15 @@ public abstract class ForkJoinTask im /** * Forks the given tasks, returning when {@code isDone} holds for * each task or an (unchecked) exception is encountered, in which - * case the exception is rethrown. If either task encounters an - * exception, the other one may be, but is not guaranteed to be, - * cancelled. If both tasks throw an exception, then this method - * throws one of them. The individual status of each task may be - * checked using {@link #getException()} and related methods. + * case the exception is rethrown. If more than one task + * encounters an exception, then this method throws any one of + * these exceptions. If any task encounters an exception, the + * other may be cancelled. However, the execution status of + * individual tasks is not guaranteed upon exceptional return. The + * status of each task may be obtained using {@link + * #getException()} and related methods to check if they have been + * cancelled, completed normally or exceptionally, or left + * unprocessed. * *

This method may be invoked only from within {@code * ForkJoinTask} computations (as may be determined using method @@ -379,12 +385,14 @@ public abstract class ForkJoinTask im /** * Forks the given tasks, returning when {@code isDone} holds for * each task or an (unchecked) exception is encountered, in which - * case the exception is rethrown. If any task encounters an - * exception, others may be, but are not guaranteed to be, - * cancelled. If more than one task encounters an exception, then - * this method throws any one of these exceptions. The individual - * status of each task may be checked using {@link #getException()} - * and related methods. + * case the exception is rethrown. If more than one task + * encounters an exception, then this method throws any one of + * these exceptions. If any task encounters an exception, others + * may be cancelled. However, the execution status of individual + * tasks is not guaranteed upon exceptional return. The status of + * each task may be obtained using {@link #getException()} and + * related methods to check if they have been cancelled, completed + * normally or exceptionally, or left unprocessed. * *

This method may be invoked only from within {@code * ForkJoinTask} computations (as may be determined using method @@ -431,14 +439,15 @@ public abstract class ForkJoinTask im /** * Forks all tasks in the specified collection, returning when * {@code isDone} holds for each task or an (unchecked) exception - * is encountered. If any task encounters an exception, others - * may be, but are not guaranteed to be, cancelled. If more than - * one task encounters an exception, then this method throws any - * one of these exceptions. The individual status of each task - * may be checked using {@link #getException()} and related - * methods. The behavior of this operation is undefined if the - * specified collection is modified while the operation is in - * progress. + * is encountered, in which case the exception is rethrown. If + * more than one task encounters an exception, then this method + * throws any one of these exceptions. If any task encounters an + * exception, others may be cancelled. However, the execution + * status of individual tasks is not guaranteed upon exceptional + * return. The status of each task may be obtained using {@link + * #getException()} and related methods to check if they have been + * cancelled, completed normally or exceptionally, or left + * unprocessed. * *

This method may be invoked only from within {@code * ForkJoinTask} computations (as may be determined using method @@ -534,7 +543,8 @@ public abstract class ForkJoinTask im } /** - * Cancels ignoring exceptions if worker is terminating + * Cancels if current thread is a terminating worker thread, + * ignoring any exceptions thrown by cancel. */ final void cancelIfTerminating() { Thread t = Thread.currentThread(); @@ -611,13 +621,14 @@ public abstract class ForkJoinTask im /** * Completes this task, and if not already aborted or cancelled, - * returning a {@code null} result upon {@code join} and related - * operations. This method may be used to provide results for - * asynchronous tasks, or to provide alternative handling for - * tasks that would not otherwise complete normally. Its use in - * other situations is discouraged. This method is - * overridable, but overridden versions must invoke {@code super} - * implementation to maintain guarantees. + * returning the given value as the result of subsequent + * invocations of {@code join} and related operations. This method + * may be used to provide results for asynchronous tasks, or to + * provide alternative handling for tasks that would not otherwise + * complete normally. Its use in other situations is + * discouraged. This method is overridable, but overridden + * versions must invoke {@code super} implementation to maintain + * guarantees. * * @param value the result value for this task */ @@ -669,7 +680,7 @@ public abstract class ForkJoinTask im boolean dec = false; // true if pool count decremented long nanos = unit.toNanos(timeout); for (;;) { - if (Thread.interrupted() && pool == null) { + if (pool == null && Thread.interrupted()) { interrupted = true; break; } @@ -754,9 +765,7 @@ public abstract class ForkJoinTask im /** * Commences performing this task and awaits its completion if * necessary, without returning its result or throwing its - * exception. This method may be useful when processing - * collections of tasks when some have been cancelled or otherwise - * known to have aborted. + * exception. */ public final void quietlyInvoke() { if (status >= 0) { @@ -1093,7 +1102,7 @@ public abstract class ForkJoinTask im private static final long serialVersionUID = -7721805057305804111L; /** - * Saves the state to a stream. + * Saves the state to a stream (that is, serializes it). * * @serialData the current run status and the exception thrown * during execution, or {@code null} if none @@ -1106,7 +1115,7 @@ public abstract class ForkJoinTask im } /** - * Reconstitutes the instance from a stream. + * Reconstitutes the instance from a stream (that is, deserializes it). * * @param s the stream */