--- jsr166/src/jsr166y/ForkJoinTask.java 2009/08/02 11:54:31 1.27 +++ jsr166/src/jsr166y/ForkJoinTask.java 2009/08/02 22:58:50 1.31 @@ -22,40 +22,42 @@ import java.util.WeakHashMap; * subtasks may be hosted by a small number of actual threads in a * ForkJoinPool, at the price of some usage limitations. * - *

A "main" ForkJoinTask begins execution when submitted to a - * {@link ForkJoinPool}. Once started, it will usually in turn start - * other subtasks. As indicated by the name of this class, many - * programs using ForkJoinTasks employ only methods {@code fork} and - * {@code join}, or derivatives such as {@code invokeAll}. However, - * this class also provides a number of other methods that can come - * into play in advanced usages, as well as extension mechanics that - * allow support of new forms of fork/join processing. + *

A "main" {@code ForkJoinTask} begins execution when submitted + * to a {@link ForkJoinPool}. Once started, it will usually in turn + * start other subtasks. As indicated by the name of this class, + * many programs using {@code ForkJoinTask} employ only methods + * {@link #fork} and {@link #join}, or derivatives such as {@link + * #invokeAll}. However, this class also provides a number of other + * methods that can come into play in advanced usages, as well as + * extension mechanics that allow support of new forms of fork/join + * processing. * - *

A ForkJoinTask is a lightweight form of {@link Future}. The - * efficiency of ForkJoinTasks stems from a set of restrictions (that - * are only partially statically enforceable) reflecting their - * intended use as computational tasks calculating pure functions or - * operating on purely isolated objects. The primary coordination - * mechanisms are {@link #fork}, that arranges asynchronous execution, - * and {@link #join}, that doesn't proceed until the task's result has - * been computed. Computations should avoid {@code synchronized} - * methods or blocks, and should minimize other blocking - * synchronization apart from joining other tasks or using - * synchronizers such as Phasers that are advertised to cooperate with - * fork/join scheduling. Tasks should also not perform blocking IO, - * and should ideally access variables that are completely independent - * of those accessed by other running tasks. Minor breaches of these - * restrictions, for example using shared output streams, may be - * tolerable in practice, but frequent use may result in poor - * performance, and the potential to indefinitely stall if the number - * of threads not waiting for IO or other external synchronization - * becomes exhausted. This usage 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 additionally include - * RejectedExecutionExceptions stemming from internal resource - * exhaustion such as failure to allocate internal task queues. + *

A {@code ForkJoinTask} is a lightweight form of {@link Future}. + * The efficiency of {@code ForkJoinTask}s stems from a set of + * restrictions (that are only partially statically enforceable) + * reflecting their intended use as computational tasks calculating + * pure functions or operating on purely isolated objects. The + * primary coordination mechanisms are {@link #fork}, that arranges + * asynchronous execution, and {@link #join}, that doesn't proceed + * until the task's result has been computed. Computations should + * avoid {@code synchronized} methods or blocks, and should minimize + * other blocking synchronization apart from joining other tasks or + * using synchronizers such as Phasers that are advertised to + * cooperate with fork/join scheduling. Tasks should also not perform + * blocking IO, and should ideally access variables that are + * completely independent of those accessed by other running + * tasks. Minor breaches of these restrictions, for example using + * shared output streams, may be tolerable in practice, but frequent + * use may result in poor performance, and the potential to + * indefinitely stall if the number of threads not waiting for IO or + * other external synchronization becomes exhausted. This usage + * 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 + * additionally include RejectedExecutionExceptions stemming from + * internal resource exhaustion such as failure to allocate internal + * task queues. * *

The primary method for awaiting completion and extracting * results of a task is {@link #join}, but there are several variants: @@ -74,7 +76,7 @@ import java.util.WeakHashMap; * performs the most common form of parallel invocation: forking a set * of tasks and joining them all. * - *

The ForkJoinTask class is not usually directly subclassed. + *

The ForkJoinTask class is not usually directly subclassed. * Instead, you subclass one of the abstract classes that support a * particular style of fork/join processing, typically {@link * RecursiveAction} for computations that do not return results, or @@ -494,13 +496,15 @@ public abstract class ForkJoinTask im /** * Arranges to asynchronously execute this task. While it is not * necessarily enforced, it is a usage error to fork a task more - * than once unless it has completed and been reinitialized. This - * method may be invoked only from within ForkJoinTask - * computations (as may be determined using method {@link - * #inForkJoinPool}). Attempts to invoke in other contexts result - * in exceptions or errors, possibly including ClassCastException. + * than once unless it has completed and been reinitialized. * - * @return {@code this}, to simplify usage. + *

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 fork() { ((ForkJoinWorkerThread) Thread.currentThread()) @@ -510,9 +514,9 @@ public abstract class ForkJoinTask im /** * Returns the result of the computation when it is ready. - * This method differs from {@code get} in that abnormal - * completion results in RuntimeExceptions or Errors, not - * ExecutionExceptions. + * This method differs from {@link #get()} in that + * abnormal completion results in {@code RuntimeException} or + * {@code Error}, not {@code ExecutionException}. * * @return the computed result */ @@ -539,19 +543,21 @@ public abstract class ForkJoinTask im } /** - * Forks the given tasks, returning when {@code isDone} holds for - * each task or an exception is encountered. This method may be - * invoked only from within ForkJoinTask computations (as may be - * determined using method {@link #inForkJoinPool}). Attempts to - * invoke in other contexts result in exceptions or errors, - * possibly including ClassCastException. + * Forks the given tasks, returning when {@code isDone} holds + * for each task or an exception is encountered. + * + *

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(ForkJoinTaskt1, ForkJoinTask t2) { + public static void invokeAll(ForkJoinTask t1, ForkJoinTask t2) { t2.fork(); t1.invoke(); t2.join(); @@ -561,13 +567,15 @@ public abstract class ForkJoinTask im * Forks the given tasks, returning when {@code isDone} holds for * each task or an exception is encountered. If any task * encounters an exception, others may be, but are not guaranteed - * to be, cancelled. This method may be invoked only from within - * ForkJoinTask computations (as may be determined using method - * {@link #inForkJoinPool}). Attempts to invoke in other contexts - * result in exceptions or errors, possibly including - * ClassCastException. + * to be, cancelled. + * + *

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}. * - * Overloadings of this method exist for the special cases + *

Overloadings of this method exist for the special cases * of one to four arguments. * * @param tasks the tasks @@ -609,13 +617,15 @@ public abstract class ForkJoinTask im /** * Forks all tasks in the collection, returning when {@code - * isDone} holds for each task or an exception is encountered. If - * any task encounters an exception, others may be, but are not - * guaranteed to be, cancelled. This method may be invoked only - * from within ForkJoinTask computations (as may be determined - * using method {@link #inForkJoinPool}). Attempts to invoke in - * other contexts result in exceptions or errors, possibly - * including ClassCastException. + * isDone} holds for each task or an exception is encountered. + * If any task encounters an exception, others may be, but are + * not guaranteed to be, cancelled. + * + *

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 @@ -696,9 +706,9 @@ public abstract class ForkJoinTask im * *

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 + *

This method is designed to be invoked by other * tasks. To terminate the current task, you can just return or * throw an unchecked exception from its computation method, or * invoke {@link #completeExceptionally}. @@ -725,8 +735,8 @@ public abstract class ForkJoinTask im /** * Returns the exception thrown by the base computation, or a - * CancellationException if cancelled, or null if none or if the - * method has not yet completed. + * {@code CancellationException} if cancelled, or {@code null} if + * none or if the method has not yet completed. * * @return the exception, or {@code null} if none */ @@ -804,11 +814,13 @@ public abstract class ForkJoinTask im * there are no potential dependencies between continuation of the * current task and that of any other task that might be executed * while helping. (This usually holds for pure divide-and-conquer - * tasks). This method may be invoked only from within - * ForkJoinTask computations (as may be determined using method - * {@link #inForkJoinPool}). Attempts to invoke in other contexts - * result in exceptions or errors, possibly including - * ClassCastException. + * tasks). + * + *

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 */ @@ -820,11 +832,13 @@ public abstract class ForkJoinTask im } /** - * Possibly executes other tasks until this task is ready. This - * method may be invoked only from within ForkJoinTask - * computations (as may be determined using method {@link - * #inForkJoinPool}). Attempts to invoke in other contexts result - * in exceptions or errors, possibly including ClassCastException. + * Possibly executes other tasks until this task is ready. + * + *

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) { @@ -865,11 +879,13 @@ public abstract class ForkJoinTask im * Possibly executes tasks until the pool hosting the current task * {@link ForkJoinPool#isQuiescent}. This method may be of use in * designs in which many tasks are forked, but none are explicitly - * joined, instead executing them until all are processed. This - * method may be invoked only from within ForkJoinTask - * computations (as may be determined using method {@link - * #inForkJoinPool}). Attempts to invoke in other contexts result - * in exceptions or errors, possibly including ClassCastException. + * joined, instead executing them until all are processed. + * + *

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()) @@ -882,8 +898,8 @@ public abstract class ForkJoinTask im * this task, but only if reuse occurs when this task has either * never been forked, or has been forked, then completed and all * outstanding joins of this task have also completed. Effects - * under any other usage conditions are not guaranteed, and are - * discouraged. This method may be useful when executing + * under any other usage conditions are not guaranteed. + * This method may be useful when executing * pre-constructed trees of subtasks in loops. */ public void reinitialize() { @@ -922,11 +938,13 @@ public abstract class ForkJoinTask im * by the current thread, and has not commenced executing in * another thread. This method may be useful when arranging * alternative local processing of tasks that could have been, but - * were not, stolen. This method may be invoked only from within - * ForkJoinTask computations (as may be determined using method - * {@link #inForkJoinPool}). Attempts to invoke in other contexts - * result in exceptions or errors, possibly including - * ClassCastException. + * were not, stolen. + * + *

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 */ @@ -939,11 +957,14 @@ public abstract class ForkJoinTask im * Returns an estimate of the number of tasks that have been * forked by the current worker thread but not yet executed. This * value may be useful for heuristic decisions about whether to - * fork other tasks. This method may be invoked only from within - * ForkJoinTask computations (as may be determined using method - * {@link #inForkJoinPool}). Attempts to invoke in other contexts - * result in exceptions or errors, possibly including - * ClassCastException. + * fork other tasks. + * + *

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() { @@ -959,11 +980,14 @@ public abstract class ForkJoinTask im * usages of ForkJoinTasks, at steady state, each worker should * aim to maintain a small constant surplus (for example, 3) of * tasks, and to process computations locally if this threshold is - * exceeded. This method may be invoked only from within - * ForkJoinTask computations (as may be determined using method - * {@link #inForkJoinPool}). Attempts to invoke in other contexts - * result in exceptions or errors, possibly including - * ClassCastException. * + * exceeded. + * + *

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() { @@ -1015,11 +1039,13 @@ public abstract class ForkJoinTask im * null even if a task exists but cannot be accessed without * contention with other threads. This method is designed * primarily to support extensions, and is unlikely to be useful - * otherwise. This method may be invoked only from within - * ForkJoinTask computations (as may be determined using method - * {@link #inForkJoinPool}). Attempts to invoke in other contexts - * result in exceptions or errors, possibly including - * ClassCastException. + * otherwise. + * + *

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 */ @@ -1032,11 +1058,13 @@ public abstract class ForkJoinTask im * Unschedules and returns, without executing, the next task * queued by the current thread but not yet executed. This method * is designed primarily to support extensions, and is unlikely to - * be useful otherwise. This method may be invoked only from - * within ForkJoinTask computations (as may be determined using - * method {@link #inForkJoinPool}). Attempts to invoke in other - * contexts result in exceptions or errors, possibly including - * ClassCastException. + * be useful otherwise. + * + *

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 */ @@ -1053,11 +1081,13 @@ public abstract class ForkJoinTask im * {@code null} result does not necessarily imply quiescence * of the pool this task is operating in. This method is designed * primarily to support extensions, and is unlikely to be useful - * otherwise. This method may be invoked only from within - * ForkJoinTask computations (as may be determined using method - * {@link #inForkJoinPool}). Attempts to invoke in other contexts - * result in exceptions or errors, possibly including - * ClassCastException. + * otherwise. + * + *

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 */ @@ -1122,9 +1152,9 @@ public abstract class ForkJoinTask im } /** - * Returns a new ForkJoinTask that performs the {@code run} - * method of the given Runnable as its action, and returns a null - * result upon {@code join}. + * Returns a new {@code ForkJoinTask} that performs the {@code run} + * method of the given {@code Runnable} as its action, and returns + * a null result upon {@link #join}. * * @param runnable the runnable action * @return the task @@ -1134,9 +1164,9 @@ public abstract class ForkJoinTask im } /** - * Returns a new ForkJoinTask that performs the {@code run} - * method of the given Runnable as its action, and returns the - * given result upon {@code join}. + * Returns a new {@code ForkJoinTask} that performs the {@code run} + * method of the given {@code Runnable} as its action, and returns + * the given result upon {@link #join}. * * @param runnable the runnable action * @param result the result upon completion @@ -1147,10 +1177,10 @@ public abstract class ForkJoinTask im } /** - * Returns a new ForkJoinTask that performs the {@code call} - * method of the given Callable as its action, and returns its - * result upon {@code join}, translating any checked - * exceptions encountered into {@code RuntimeException}. + * Returns a new {@code ForkJoinTask} that performs the {@code call} + * method of the given {@code Callable} as its action, and returns + * its result upon {@link #join}, translating any checked exceptions + * encountered into {@code RuntimeException}. * * @param callable the callable action * @return the task