--- jsr166/src/jsr166y/ForkJoinPool.java 2009/07/29 12:05:55 1.30 +++ jsr166/src/jsr166y/ForkJoinPool.java 2009/08/03 00:53:15 1.40 @@ -21,36 +21,37 @@ import java.util.concurrent.atomic.Atomi /** * An {@link ExecutorService} for running {@link ForkJoinTask}s. - * A ForkJoinPool provides the entry point for submissions from - * non-ForkJoinTasks, as well as management and monitoring operations. - * Normally a single ForkJoinPool is used for a large number of - * submitted tasks. Otherwise, use would not usually outweigh the - * construction and bookkeeping overhead of creating a large set of - * threads. + * A {@code ForkJoinPool} provides the entry point for submissions + * from non-{@code ForkJoinTask}s, as well as management and + * monitoring operations. Normally a single {@code ForkJoinPool} is + * used for a large number of submitted tasks. Otherwise, use would + * not usually outweigh the construction and bookkeeping overhead of + * creating a large set of threads. * - *
ForkJoinPools differ from other kinds of Executors mainly in - * that they provide work-stealing: all threads in the pool - * attempt to find and execute subtasks created by other active tasks - * (eventually blocking if none exist). This makes them efficient when - * most tasks spawn other subtasks (as do most ForkJoinTasks), as well - * as the mixed execution of some plain Runnable- or Callable- based - * activities along with ForkJoinTasks. When setting {@linkplain - * #setAsyncMode async mode}, a ForkJoinPool may also be appropriate - * for use with fine-grained tasks that are never joined. Otherwise, - * other ExecutorService implementations are typically more + *
{@code ForkJoinPool}s differ from other kinds of {@link + * Executor}s mainly in that they provide work-stealing: all + * threads in the pool attempt to find and execute subtasks created by + * other active tasks (eventually blocking if none exist). This makes + * them efficient when most tasks spawn other subtasks (as do most + * {@code ForkJoinTask}s), as well as the mixed execution of some + * plain {@code Runnable}- or {@code Callable}- based activities along + * with {@code ForkJoinTask}s. When setting {@linkplain #setAsyncMode + * async mode}, a {@code ForkJoinPool} may also be appropriate for use + * with fine-grained tasks that are never joined. Otherwise, other + * {@code ExecutorService} implementations are typically more * appropriate choices. * - *
A ForkJoinPool may be constructed with a given parallelism level - * (target pool size), which it attempts to maintain by dynamically - * adding, suspending, or resuming threads, even if some tasks are - * waiting to join others. However, no such adjustments are performed - * in the face of blocked IO or other unmanaged synchronization. The - * nested {@link ManagedBlocker} interface enables extension of - * the kinds of synchronization accommodated. The target parallelism - * level may also be changed dynamically ({@link #setParallelism}) - * and thread construction can be limited using methods - * {@link #setMaximumPoolSize} and/or - * {@link #setMaintainsParallelism}. + *
A {@code ForkJoinPool} may be constructed with a given + * parallelism level (target pool size), which it attempts to maintain + * by dynamically adding, suspending, or resuming threads, even if + * some tasks are waiting to join others. However, no such adjustments + * are performed in the face of blocked IO or other unmanaged + * synchronization. The nested {@link ManagedBlocker} interface + * enables extension of the kinds of synchronization accommodated. + * The target parallelism level may also be changed dynamically + * ({@link #setParallelism}) and thread construction can be limited + * using methods {@link #setMaximumPoolSize} and/or {@link + * #setMaintainsParallelism}. * *
In addition to execution and lifecycle control methods, this * class provides status check methods (for example @@ -62,7 +63,7 @@ import java.util.concurrent.atomic.Atomi *
Implementation notes: This implementation restricts the
* maximum number of running threads to 32767. Attempts to create
* pools with greater than the maximum result in
- * IllegalArgumentExceptions.
+ * {@code IllegalArgumentException}.
*
* @since 1.7
* @author Doug Lea
@@ -81,10 +82,10 @@ public class ForkJoinPool extends Abstra
private static final int MAX_THREADS = 0x7FFF;
/**
- * Factory for creating new ForkJoinWorkerThreads. A
- * ForkJoinWorkerThreadFactory must be defined and used for
- * ForkJoinWorkerThread subclasses that extend base functionality
- * or initialize threads with different contexts.
+ * Factory for creating new {@link ForkJoinWorkerThread}s.
+ * A {@code ForkJoinWorkerThreadFactory} must be defined and used
+ * for {@code ForkJoinWorkerThread} subclasses that extend base
+ * functionality or initialize threads with different contexts.
*/
public static interface ForkJoinWorkerThreadFactory {
/**
@@ -578,7 +579,7 @@ public class ForkJoinPool extends Abstra
* @throws NullPointerException if task is null
* @throws RejectedExecutionException if pool is shut down
*/
- public A {@code ManagedBlocker} provides two methods.
* Method {@code isReleasable} must return {@code true} if
* blocking is not necessary. Method {@code block} blocks the
* current thread if necessary (perhaps internally invoking
- * {@code isReleasable} before actually blocking.).
+ * {@code isReleasable} before actually blocking).
*
* For example, here is a ManagedBlocker based on a
* ReentrantLock:
@@ -1817,25 +1781,27 @@ public class ForkJoinPool extends Abstra
/**
* Blocks in accord with the given blocker. If the current thread
- * is a ForkJoinWorkerThread, this method possibly arranges for a
- * spare thread to be activated if necessary to ensure parallelism
- * while the current thread is blocked. If
- * {@code maintainParallelism} is {@code true} and the pool supports
- * it ({@link #getMaintainsParallelism}), this method attempts to
- * maintain the pool's nominal parallelism. Otherwise it activates
- * a thread only if necessary to avoid complete starvation. This
- * option may be preferable when blockages use timeouts, or are
- * almost always brief.
+ * is a {@link ForkJoinWorkerThread}, this method possibly
+ * arranges for a spare thread to be activated if necessary to
+ * ensure parallelism while the current thread is blocked.
+ *
+ * If {@code maintainParallelism} is {@code true} and the pool
+ * supports it ({@link #getMaintainsParallelism}), this method
+ * attempts to maintain the pool's nominal parallelism. Otherwise
+ * it activates a thread only if necessary to avoid complete
+ * starvation. This option may be preferable when blockages use
+ * timeouts, or are almost always brief.
*
- * If the caller is not a ForkJoinTask, this method is behaviorally
- * equivalent to
+ * If the caller is not a {@link ForkJoinTask}, this method is
+ * behaviorally equivalent to
* {@code
* while (!blocker.isReleasable())
* if (blocker.block())
* return;
* }
- * If the caller is a ForkJoinTask, then the pool may first
- * be expanded to ensure parallelism, and later adjusted.
+ *
+ * If the caller is a {@code ForkJoinTask}, then the pool may
+ * first be expanded to ensure parallelism, and later adjusted.
*
* @param blocker the blocker
* @param maintainParallelism if {@code true} and supported by
@@ -1867,14 +1833,16 @@ public class ForkJoinPool extends Abstra
do {} while (!blocker.isReleasable() && !blocker.block());
}
- // AbstractExecutorService overrides
+ // AbstractExecutorService overrides. These rely on undocumented
+ // fact that ForkJoinTask.adapt returns ForkJoinTasks that also
+ // implement RunnableFuture.
protected