--- jsr166/src/jsr166y/ForkJoinPool.java	2009/07/27 20:57:44	1.28
+++ jsr166/src/jsr166y/ForkJoinPool.java	2009/08/02 17:55:51	1.39
@@ -20,49 +20,50 @@ import java.util.concurrent.atomic.Atomi
 import java.util.concurrent.atomic.AtomicLong;
 
 /**
- * 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.
+ * An {@link ExecutorService} for running {@link ForkJoinTask}s.
+ * 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.
  *
- * <p>ForkJoinPools differ from other kinds of Executors mainly in
- * that they provide <em>work-stealing</em>: 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
- * {@code setAsyncMode}, a ForkJoinPools may also be appropriate for
- * use with fine-grained tasks that are never joined. Otherwise, other
- * ExecutorService implementations are typically more appropriate
- * choices.
+ * <p>{@code ForkJoinPool}s differ from other kinds of {@link
+ * Executor}s mainly in that they provide <em>work-stealing</em>: 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.
  *
- * <p>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 {@code ManagedBlocker} interface enables extension of
- * the kinds of synchronization accommodated.  The target parallelism
- * level may also be changed dynamically ({@code setParallelism})
- * and thread construction can be limited using methods
- * {@code setMaximumPoolSize} and/or
- * {@code setMaintainsParallelism}.
+ * <p>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}.
  *
  * <p>In addition to execution and lifecycle control methods, this
  * class provides status check methods (for example
- * {@code getStealCount}) that are intended to aid in developing,
+ * {@link #getStealCount}) that are intended to aid in developing,
  * tuning, and monitoring fork/join applications. Also, method
- * {@code toString} returns indications of pool state in a
+ * {@link #toString} returns indications of pool state in a
  * convenient form for informal monitoring.
  *
  * <p><b>Implementation notes</b>: 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 <T> void execute(ForkJoinTask<T> task) {
+    public void execute(ForkJoinTask<?> task) {
         doSubmit(task);
     }
 
@@ -589,18 +590,18 @@ public class ForkJoinPool extends Abstra
         if (task instanceof ForkJoinTask<?>) // avoid re-wrap
             job = (ForkJoinTask<?>) task;
         else
-            job = new AdaptedRunnable<Void>(task, null);
+            job = ForkJoinTask.adapt(task, null);
         doSubmit(job);
     }
 
     public <T> ForkJoinTask<T> submit(Callable<T> task) {
-        ForkJoinTask<T> job = new AdaptedCallable<T>(task);
+        ForkJoinTask<T> job = ForkJoinTask.adapt(task);
         doSubmit(job);
         return job;
     }
 
     public <T> ForkJoinTask<T> submit(Runnable task, T result) {
-        ForkJoinTask<T> job = new AdaptedRunnable<T>(task, result);
+        ForkJoinTask<T> job = ForkJoinTask.adapt(task, result);
         doSubmit(job);
         return job;
     }
@@ -610,7 +611,7 @@ public class ForkJoinPool extends Abstra
         if (task instanceof ForkJoinTask<?>) // avoid re-wrap
             job = (ForkJoinTask<?>) task;
         else
-            job = new AdaptedRunnable<Void>(task, null);
+            job = ForkJoinTask.adapt(task, null);
         doSubmit(job);
         return job;
     }
@@ -629,65 +630,12 @@ public class ForkJoinPool extends Abstra
         return task;
     }
 
-    /**
-     * Adaptor for Runnables. This implements RunnableFuture
-     * to be compliant with AbstractExecutorService constraints.
-     */
-    static final class AdaptedRunnable<T> extends ForkJoinTask<T>
-        implements RunnableFuture<T> {
-        final Runnable runnable;
-        final T resultOnCompletion;
-        T result;
-        AdaptedRunnable(Runnable runnable, T result) {
-            if (runnable == null) throw new NullPointerException();
-            this.runnable = runnable;
-            this.resultOnCompletion = result;
-        }
-        public T getRawResult() { return result; }
-        public void setRawResult(T v) { result = v; }
-        public boolean exec() {
-            runnable.run();
-            result = resultOnCompletion;
-            return true;
-        }
-        public void run() { invoke(); }
-        private static final long serialVersionUID = 5232453952276885070L;
-    }
-
-    /**
-     * Adaptor for Callables
-     */
-    static final class AdaptedCallable<T> extends ForkJoinTask<T>
-        implements RunnableFuture<T> {
-        final Callable<T> callable;
-        T result;
-        AdaptedCallable(Callable<T> callable) {
-            if (callable == null) throw new NullPointerException();
-            this.callable = callable;
-        }
-        public T getRawResult() { return result; }
-        public void setRawResult(T v) { result = v; }
-        public boolean exec() {
-            try {
-                result = callable.call();
-                return true;
-            } catch (Error err) {
-                throw err;
-            } catch (RuntimeException rex) {
-                throw rex;
-            } catch (Exception ex) {
-                throw new RuntimeException(ex);
-            }
-        }
-        public void run() { invoke(); }
-        private static final long serialVersionUID = 2838392045355241008L;
-    }
 
     public <T> List<Future<T>> invokeAll(Collection<? extends Callable<T>> tasks) {
         ArrayList<ForkJoinTask<T>> forkJoinTasks =
             new ArrayList<ForkJoinTask<T>>(tasks.size());
         for (Callable<T> task : tasks)
-            forkJoinTasks.add(new AdaptedCallable<T>(task));
+            forkJoinTasks.add(ForkJoinTask.adapt(task));
         invoke(new InvokeAll<T>(forkJoinTasks));
 
         @SuppressWarnings({"unchecked", "rawtypes"})
@@ -815,7 +763,7 @@ public class ForkJoinPool extends Abstra
     /**
      * Returns the number of worker threads that have started but not
      * yet terminated.  This result returned by this method may differ
-     * from {@code getParallelism} when threads are created to
+     * from {@link #getParallelism} when threads are created to
      * maintain parallelism when others are cooperatively blocked.
      *
      * @return the number of worker threads
@@ -840,7 +788,7 @@ public class ForkJoinPool extends Abstra
      * Setting this value has no effect on current pool size. It
      * controls construction of new threads.
      *
-     * @throws IllegalArgumentException if negative or greater then
+     * @throws IllegalArgumentException if negative or greater than
      * internal implementation limit
      */
     public void setMaximumPoolSize(int newMax) {
@@ -877,12 +825,13 @@ public class ForkJoinPool extends Abstra
      * tasks that are never joined. This mode may be more appropriate
      * than default locally stack-based mode in applications in which
      * worker threads only process asynchronous tasks.  This method is
-     * designed to be invoked only when pool is quiescent, and
+     * designed to be invoked only when the pool is quiescent, and
      * typically only before any tasks are submitted. The effects of
      * invocations at other times may be unpredictable.
      *
-     * @param async if true, use locally FIFO scheduling
+     * @param async if {@code true}, use locally FIFO scheduling
      * @return the previous mode
+     * @see #getAsyncMode
      */
     public boolean setAsyncMode(boolean async) {
         boolean oldMode = locallyFifo;
@@ -903,6 +852,7 @@ public class ForkJoinPool extends Abstra
      * scheduling mode for forked tasks that are never joined.
      *
      * @return {@code true} if this pool uses async mode
+     * @see #setAsyncMode
      */
     public boolean getAsyncMode() {
         return locallyFifo;
@@ -1054,7 +1004,7 @@ public class ForkJoinPool extends Abstra
      * @param c the collection to transfer elements into
      * @return the number of elements transferred
      */
-    protected int drainTasksTo(Collection<ForkJoinTask<?>> c) {
+    protected int drainTasksTo(Collection<? super ForkJoinTask<?>> c) {
         int n = submissionQueue.drainTo(c);
         ForkJoinWorkerThread[] ws = workers;
         if (ws != null) {
@@ -1120,8 +1070,22 @@ public class ForkJoinPool extends Abstra
     public void shutdown() {
         checkPermission();
         transitionRunStateTo(SHUTDOWN);
-        if (canTerminateOnShutdown(runControl))
+        if (canTerminateOnShutdown(runControl)) {
+            if (workers == null) { // shutting down before workers created
+                final ReentrantLock lock = this.workerLock;
+                lock.lock();
+                try {
+                    if (workers == null) {
+                        terminate();
+                        transitionRunStateTo(TERMINATED);
+                        termination.signalAll();
+                    }
+                } finally {
+                    lock.unlock();
+                }
+            }
             terminateOnShutdown();
+        }
     }
 
     /**
@@ -1131,7 +1095,7 @@ public class ForkJoinPool extends Abstra
      * method may or may not be rejected. Unlike some other executors,
      * this method cancels rather than collects non-executed tasks
      * upon termination, so always returns an empty list. However, you
-     * can use method {@code drainTasksTo} before invoking this
+     * can use method {@link #drainTasksTo} before invoking this
      * method to transfer unexecuted tasks to another collection.
      *
      * @return an empty list
@@ -1772,7 +1736,9 @@ public class ForkJoinPool extends Abstra
 
     /**
      * Interface for extending managed parallelism for tasks running
-     * in ForkJoinPools. A ManagedBlocker provides two methods.
+     * in {@link ForkJoinPool}s.
+     *
+     * <p>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
@@ -1815,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.
+     *
+     * <p>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.
      *
-     * <p> If the caller is not a ForkJoinTask, this method is behaviorally
-     * equivalent to
+     * <p>If the caller is not a {@link ForkJoinTask}, this method is
+     * behaviorally equivalent to
      *  <pre> {@code
      * while (!blocker.isReleasable())
      *   if (blocker.block())
      *     return;
      * }</pre>
-     * 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
@@ -1865,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 <T> RunnableFuture<T> newTaskFor(Runnable runnable, T value) {
-        return new AdaptedRunnable<T>(runnable, value);
+        return (RunnableFuture<T>) ForkJoinTask.adapt(runnable, value);
     }
 
     protected <T> RunnableFuture<T> newTaskFor(Callable<T> callable) {
-        return new AdaptedCallable<T>(callable);
+        return (RunnableFuture<T>) ForkJoinTask.adapt(callable);
     }
 
     // Unsafe mechanics