--- jsr166/src/jsr166y/ForkJoinTask.java 2009/08/02 17:02:06 1.28 +++ jsr166/src/jsr166y/ForkJoinTask.java 2009/08/03 13:01:15 1.32 @@ -12,6 +12,7 @@ import java.io.Serializable; import java.util.Collection; import java.util.Collections; import java.util.List; +import java.util.RandomAccess; import java.util.Map; import java.util.WeakHashMap; @@ -54,7 +55,7 @@ import java.util.WeakHashMap; * restriction is in part enforced by not permitting checked * exceptions such as {@code IOExceptions} to be thrown. However, * computations may still encounter unchecked exceptions, that are - * rethrown to callers attempting join them. These exceptions may + * rethrown to callers attempting to join them. These exceptions may * additionally include RejectedExecutionExceptions stemming from * internal resource exhaustion such as failure to allocate internal * task queues. @@ -85,30 +86,30 @@ import java.util.WeakHashMap; * established in a constructor, and then defines a {@code compute} * method that somehow uses the control methods supplied by this base * class. While these methods have {@code public} access (to allow - * instances of different task subclasses to call each others + * instances of different task subclasses to call each other's * methods), some of them may only be called from within other * ForkJoinTasks (as may be determined using method {@link * #inForkJoinPool}). Attempts to invoke them in other contexts * result in exceptions or errors, possibly including * ClassCastException. * - *
Most base support methods are {@code final} because their - * implementations are intrinsically tied to the underlying - * lightweight task scheduling framework, and so cannot be overridden. - * Developers creating new basic styles of fork/join processing should - * minimally implement {@code protected} methods - * {@link #exec}, {@link #setRawResult}, and - * {@link #getRawResult}, while also introducing an abstract - * computational method that can be implemented in its subclasses, - * possibly relying on other {@code protected} methods provided - * by this class. + *
Most base support methods are {@code final}, to prevent + * overriding of implementations that are intrinsically tied to the + * underlying lightweight task scheduling framework. Developers + * creating new basic styles of fork/join processing should minimally + * implement {@code protected} methods {@link #exec}, {@link + * #setRawResult}, and {@link #getRawResult}, while also introducing + * an abstract computational method that can be implemented in its + * subclasses, possibly relying on other {@code protected} methods + * provided by this class. * *
ForkJoinTasks should perform relatively small amounts of - * computations, otherwise splitting into smaller tasks. As a very - * rough rule of thumb, a task should perform more than 100 and less - * than 10000 basic computational steps. If tasks are too big, then - * parallelism cannot improve throughput. If too small, then memory - * and internal task maintenance overhead may overwhelm processing. + * computation. Large tasks should be split into smaller subtasks, + * usually via recursive decomposition. As a very rough rule of thumb, + * a task should perform more than 100 and less than 10000 basic + * computational steps. If tasks are too big, then parallelism cannot + * improve throughput. If too small, then memory and internal task + * maintenance overhead may overwhelm processing. * *
This class provides {@code adapt} methods for {@link * java.lang.Runnable} and {@link java.util.concurrent.Callable}, that @@ -116,11 +117,10 @@ import java.util.WeakHashMap; * kinds of tasks. When all tasks are of this form, consider using a * pool in {@link ForkJoinPool#setAsyncMode}. * - *
ForkJoinTasks are {@code Serializable}, which enables them - * to be used in extensions such as remote execution frameworks. It is - * in general sensible to serialize tasks only before or after, but - * not during execution. Serialization is not relied on during - * execution itself. + *
ForkJoinTasks are {@code Serializable}, which enables them to be
+ * used in extensions such as remote execution frameworks. It is
+ * sensible to serialize tasks only before or after, but not during,
+ * execution. Serialization is not relied on during execution itself.
*
* @since 1.7
* @author Doug Lea
@@ -496,13 +496,15 @@ public abstract class ForkJoinTask This method may be invoked only from within {@code
+ * ForkJoinTask} computations (as may be determined using method
+ * {@link #inForkJoinPool}). Attempts to invoke in other contexts
+ * result in exceptions or errors, possibly including {@code
+ * ClassCastException}.
+ *
+ * @return {@code this}, to simplify usage
*/
public final ForkJoinTask This method may be invoked only from within {@code
+ * ForkJoinTask} computations (as may be determined using method
+ * {@link #inForkJoinPool}). Attempts to invoke in other contexts
+ * result in exceptions or errors, possibly including {@code
+ * ClassCastException}.
*
* @param t1 the first task
* @param t2 the second task
* @throws NullPointerException if any task is null
* @throws RuntimeException or Error if a task did so
*/
- public static void invokeAll(ForkJoinTask>t1, ForkJoinTask> t2) {
+ public static void invokeAll(ForkJoinTask> t1, ForkJoinTask> t2) {
t2.fork();
t1.invoke();
t2.join();
@@ -563,14 +567,13 @@ public abstract class ForkJoinTask This method may be invoked only from within {@code
+ * ForkJoinTask} computations (as may be determined using method
+ * {@link #inForkJoinPool}). Attempts to invoke in other contexts
+ * result in exceptions or errors, possibly including {@code
+ * ClassCastException}.
*
* @param tasks the tasks
* @throws NullPointerException if tasks or any element are null
@@ -610,14 +613,18 @@ public abstract class ForkJoinTask This method may be invoked only from within {@code
+ * ForkJoinTask} computations (as may be determined using method
+ * {@link #inForkJoinPool}). Attempts to invoke in other contexts
+ * result in exceptions or errors, possibly including {@code
+ * ClassCastException}.
*
* @param tasks the collection of tasks
* @return the tasks argument, to simplify usage
@@ -625,7 +632,7 @@ public abstract class ForkJoinTask This method may be overridden in subclasses, but if so, must
* still ensure that these minimal properties hold. In particular,
- * the cancel method itself must not throw exceptions.
+ * the {@code cancel} method itself must not throw exceptions.
*
* This method is designed to be invoked by other
* tasks. To terminate the current task, you can just return or
@@ -727,8 +734,8 @@ public abstract class ForkJoinTask This method may be invoked only from within {@code
+ * ForkJoinTask} computations (as may be determined using method
+ * {@link #inForkJoinPool}). Attempts to invoke in other contexts
+ * result in exceptions or errors, possibly including {@code
+ * ClassCastException}.
*
* @return the computed result
*/
@@ -823,10 +832,14 @@ public abstract class ForkJoinTask This method may be invoked only from within {@code
+ * ForkJoinTask} computations (as may be determined using method
+ * {@link #inForkJoinPool}). Attempts to invoke in other contexts
+ * result in exceptions or errors, possibly including {@code
+ * ClassCastException}.
*/
public final void quietlyHelpJoin() {
if (status >= 0) {
@@ -867,11 +880,13 @@ public abstract class ForkJoinTask This method may be invoked only from within {@code
+ * ForkJoinTask} computations (as may be determined using method
+ * {@link #inForkJoinPool}). Attempts to invoke in other contexts
+ * result in exceptions or errors, possibly including {@code
+ * ClassCastException}.
*/
public static void helpQuiesce() {
((ForkJoinWorkerThread) Thread.currentThread())
@@ -884,8 +899,8 @@ public abstract class ForkJoinTask This method may be invoked only from within {@code
+ * ForkJoinTask} computations (as may be determined using method
+ * {@link #inForkJoinPool}). Attempts to invoke in other contexts
+ * result in exceptions or errors, possibly including {@code
+ * ClassCastException}.
*
* @return {@code true} if unforked
*/
@@ -941,11 +958,14 @@ public abstract class ForkJoinTask This method may be invoked only from within {@code
+ * ForkJoinTask} computations (as may be determined using method
+ * {@link #inForkJoinPool}). Attempts to invoke in other contexts
+ * result in exceptions or errors, possibly including {@code
+ * ClassCastException}.
+ *
* @return the number of tasks
*/
public static int getQueuedTaskCount() {
@@ -961,11 +981,14 @@ public abstract class ForkJoinTask This method may be invoked only from within {@code
+ * ForkJoinTask} computations (as may be determined using method
+ * {@link #inForkJoinPool}). Attempts to invoke in other contexts
+ * result in exceptions or errors, possibly including {@code
+ * ClassCastException}.
+ *
* @return the surplus number of tasks, which may be negative
*/
public static int getSurplusQueuedTaskCount() {
@@ -1017,11 +1040,13 @@ public abstract class ForkJoinTask This method may be invoked only from within {@code
+ * ForkJoinTask} computations (as may be determined using method
+ * {@link #inForkJoinPool}). Attempts to invoke in other contexts
+ * result in exceptions or errors, possibly including {@code
+ * ClassCastException}.
*
* @return the next task, or {@code null} if none are available
*/
@@ -1034,11 +1059,13 @@ public abstract class ForkJoinTask This method may be invoked only from within {@code
+ * ForkJoinTask} computations (as may be determined using method
+ * {@link #inForkJoinPool}). Attempts to invoke in other contexts
+ * result in exceptions or errors, possibly including {@code
+ * ClassCastException}.
*
* @return the next task, or {@code null} if none are available
*/
@@ -1055,11 +1082,13 @@ public abstract class ForkJoinTask This method may be invoked only from within {@code
+ * ForkJoinTask} computations (as may be determined using method
+ * {@link #inForkJoinPool}). Attempts to invoke in other contexts
+ * result in exceptions or errors, possibly including {@code
+ * ClassCastException}.
*
* @return a task, or {@code null} if none are available
*/
@@ -1124,9 +1153,9 @@ public abstract class ForkJoinTask