{@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 {@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 {@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 + *
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 stalled 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}. + * ({@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 @@ -60,11 +62,32 @@ 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 explicitly {@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 + * pools with greater than the maximum number result in * {@code IllegalArgumentException}. * + *
This implementation rejects submitted tasks (that is, by throwing
+ * {@link RejectedExecutionException}) only when the pool is shut down.
+ *
* @since 1.7
* @author Doug Lea
*/
@@ -92,7 +115,7 @@ public class ForkJoinPool extends Abstra
* Returns a new worker thread operating in the given pool.
*
* @param pool the pool this thread works in
- * @throws NullPointerException if pool is null
+ * @throws NullPointerException if the pool is null
*/
public ForkJoinWorkerThread newThread(ForkJoinPool pool);
}
@@ -343,9 +366,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
@@ -358,12 +381,13 @@ 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
+ * equal to zero, or greater than implementation limit
* @throws SecurityException if a security manager exists and
* the caller is not permitted to modify threads
* because it does not hold {@link
@@ -374,12 +398,12 @@ 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
+ * @throws NullPointerException if the factory is null
* @throws SecurityException if a security manager exists and
* the caller is not permitted to modify threads
* because it does not hold {@link
@@ -390,13 +414,14 @@ 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
- * @throws NullPointerException if factory is null
+ * equal to zero, or greater than implementation limit
+ * @throws NullPointerException if the factory is null
* @throws SecurityException if a security manager exists and
* the caller is not permitted to modify threads
* because it does not hold {@link
@@ -424,7 +449,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;
@@ -445,8 +470,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;
}
/**
@@ -564,8 +597,9 @@ public class ForkJoinPool extends Abstra
*
* @param task the task
* @return the task's result
- * @throws NullPointerException if task is null
- * @throws RejectedExecutionException if pool is shut down
+ * @throws NullPointerException if the task is null
+ * @throws RejectedExecutionException if the task cannot be
+ * scheduled for execution
*/
public