--- jsr166/src/jsr166y/ForkJoinTask.java 2010/08/11 19:44:30 1.54
+++ jsr166/src/jsr166y/ForkJoinTask.java 2010/09/04 11:33:53 1.57
@@ -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) {
@@ -214,7 +215,9 @@ public abstract class ForkJoinTask im
}
/**
- * Blocks a worker thread until completion. Called only by pool.
+ * Blocks a worker thread until completion. Called only by
+ * pool. Currently unused -- pool-based waits use timeout
+ * version below.
*/
final void internalAwaitDone() {
int s; // the odd construction reduces lock bias effects
@@ -231,6 +234,28 @@ public abstract class ForkJoinTask im
}
/**
+ * Blocks a worker thread until completed or timed out. Called
+ * only by pool.
+ *
+ * @return status on exit
+ */
+ final int internalAwaitDone(long millis) {
+ int s;
+ if ((s = status) >= 0) {
+ try {
+ synchronized(this) {
+ if (UNSAFE.compareAndSwapInt(this, statusOffset, s,SIGNAL))
+ wait(millis, 0);
+ }
+ } catch (InterruptedException ie) {
+ cancelIfTerminating();
+ }
+ s = status;
+ }
+ return s;
+ }
+
+ /**
* Blocks a non-worker-thread until completion.
*/
private void externalAwaitDone() {
@@ -314,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
*/
@@ -330,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
@@ -355,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
@@ -407,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
@@ -510,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();
@@ -1069,7 +1103,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
@@ -1082,7 +1116,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
*/