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 - * appropriate choices. + *
A {@code ForkJoinPool} differs from other kinds of {@link + * ExecutorService} mainly by virtue of employing + * work-stealing: all threads in the pool attempt to find and + * execute subtasks created by other active tasks (eventually blocking + * waiting for work if none exist). This enables efficient processing + * when most tasks spawn other subtasks (as do most {@code + * ForkJoinTask}s). A {@code ForkJoinPool} may also be used for 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 of any form + * 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} is constructed with a given target + * parallelism level; by default, equal to the number of available + * processors. Unless configured otherwise via {@link + * #setMaintainsParallelism}, the pool attempts to maintain this + * number of active (or available) threads by dynamically adding, + * suspending, or resuming internal worker 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}). The total number of threads may be + * limited using method {@link #setMaximumPoolSize}, in which case it + * may become possible for the activities of a pool to stall due to + * the lack of available threads to process new tasks. * *
In addition to execution and lifecycle control methods, this * class provides status check methods (for example @@ -59,10 +62,28 @@ import java.util.concurrent.atomic.Atomi * {@link #toString} returns indications of pool state in a * convenient form for informal monitoring. * + *
Sample Usage. Normally a single {@code ForkJoinPool} is + * used for all parallel task execution in a program or subsystem. + * Otherwise, use would not usually outweigh the construction and + * bookkeeping overhead of creating a large set of threads. For + * example a common pool could be used for the {@code SortTasks} + * illustrated in {@link RecursiveAction}. Because {@code + * ForkJoinPool} uses threads in {@linkplain java.lang.Thread#isDaemon + * daemon} mode, there is typically no need to explictly {@link + * #shutdown} such a pool upon program exit. + * + *
+ * static final ForkJoinPool mainPool = new ForkJoinPool();
+ * ...
+ * public void sort(long[] array) {
+ * mainPool.invoke(new SortTask(array, 0, array.length));
+ * }
+ *
+ *
* 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
@@ -342,9 +363,9 @@ public class ForkJoinPool extends Abstra
// Constructors
/**
- * Creates a ForkJoinPool with a pool size equal to the number of
- * processors available on the system, using the default
- * ForkJoinWorkerThreadFactory.
+ * Creates a {@code ForkJoinPool} with parallelism equal to {@link
+ * java.lang.Runtime#availableProcessors}, and using the {@linkplain
+ * #defaultForkJoinWorkerThreadFactory default thread factory}.
*
* @throws SecurityException if a security manager exists and
* the caller is not permitted to modify threads
@@ -357,10 +378,11 @@ public class ForkJoinPool extends Abstra
}
/**
- * Creates a ForkJoinPool with the indicated parallelism level
- * threads and using the default ForkJoinWorkerThreadFactory.
+ * Creates a {@code ForkJoinPool} with the indicated parallelism
+ * level and using the {@linkplain
+ * #defaultForkJoinWorkerThreadFactory default thread factory}.
*
- * @param parallelism the number of worker threads
+ * @param parallelism the parallelism level
* @throws IllegalArgumentException if parallelism less than or
* equal to zero
* @throws SecurityException if a security manager exists and
@@ -373,9 +395,9 @@ public class ForkJoinPool extends Abstra
}
/**
- * Creates a ForkJoinPool with parallelism equal to the number of
- * processors available on the system and using the given
- * ForkJoinWorkerThreadFactory.
+ * Creates a {@code ForkJoinPool} with parallelism equal to {@link
+ * java.lang.Runtime#availableProcessors}, and using the given
+ * thread factory.
*
* @param factory the factory for creating new threads
* @throws NullPointerException if factory is null
@@ -389,9 +411,10 @@ public class ForkJoinPool extends Abstra
}
/**
- * Creates a ForkJoinPool with the given parallelism and factory.
+ * Creates a {@code ForkJoinPool} with the given parallelism and
+ * thread factory.
*
- * @param parallelism the targeted number of worker threads
+ * @param parallelism the parallelism level
* @param factory the factory for creating new threads
* @throws IllegalArgumentException if parallelism less than or
* equal to zero, or greater than implementation limit
@@ -423,7 +446,7 @@ public class ForkJoinPool extends Abstra
* Creates a new worker thread using factory.
*
* @param index the index to assign worker
- * @return new worker, or null of factory failed
+ * @return new worker, or null if factory failed
*/
private ForkJoinWorkerThread createWorker(int index) {
Thread.UncaughtExceptionHandler h = ueh;
@@ -444,8 +467,16 @@ public class ForkJoinPool extends Abstra
* Currently requires size to be a power of two.
*/
private static int arraySizeFor(int poolSize) {
- return (poolSize <= 1) ? 1 :
- (1 << (32 - Integer.numberOfLeadingZeros(poolSize-1)));
+ if (poolSize <= 1)
+ return 1;
+ // See Hackers Delight, sec 3.2
+ int c = poolSize >= MAX_THREADS ? MAX_THREADS : (poolSize - 1);
+ c |= c >>> 1;
+ c |= c >>> 2;
+ c |= c >>> 4;
+ c |= c >>> 8;
+ c |= c >>> 16;
+ return c + 1;
}
/**
@@ -578,7 +609,7 @@ public class ForkJoinPool extends Abstra
* @throws NullPointerException if task is null
* @throws RejectedExecutionException if pool is shut down
*/
- public For example, here is a ManagedBlocker based on a
* ReentrantLock:
@@ -1780,25 +1824,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