FJP.CommonPool and VM shutdown

[Doug Lea]

On 01/01/13 06:55, Doug Lea wrote:
>
> While writing some CompletableFuture test code, I
> realized that there's a potential unhappy surprise
> lurking in code of the form:
>
> class X {
>    public static void main(String[] args) {
>       new ComputationUsingCommonPool(...).fork();
>    }
> }
>
>
> Because the common pool uses daemon threads, it is
> OK for the VM to shutdown immediately after the fork().
>

Solved as follows:

The use cases are identical to those that, for other
pools, require awaitTermination. So I added similarly-spec'ed
method awaitQuiescence, plus a static quiesceCommonPool.
Plus a simple tie-in so that awaitTermination relays
to awaitQuiescence for the common pool (although always
returns false), which eliminates need for user special
casing of equivalent functionality for common vs other pools.

Here's javadoc for these, plus added text for commonPool()

     /**
      * Returns the common pool instance. This pool is statically
      * constructed; its run state is unaffected by attempts to {@link
      * #shutdown} or {@link #shutdownNow}. However this pool and any
      * ongoing processing are automatically terminated upon program
      * {@link System#exit}.  Any program that relies on asynchronous
      * task processing to complete before program termination should
      * invoke {@link #quiesceCommonPool}, or the timeout-based {@code
      * commonPool().}{@link #awaitQuiescence}, before exit.
      *
      * @return the common pool instance
      */
     public static ForkJoinPool commonPool();

     /**
      * Waits and/or attempts to assist performing tasks until this
      * pool {@link #isQuiescent} or the indicated timeout elapses.
      *
      * @param timeout the maximum time to wait
      * @param unit the time unit of the timeout argument
      * @return {@code true} if quiescent; {@code false} if the
      * timeout elapsed.
      */
     public boolean awaitQuiescence(long timeout, TimeUnit unit);

     /**
      * Waits and/or attempts to assist performing tasks indefinitely
      * until the {@link #commonPool()} {@link #isQuiescent}
      */
     public static void quiesceCommonPool() {
         common.awaitQuiescence(Long.MAX_VALUE, TimeUnit.NANOSECONDS);
     }

     /**
      * Blocks until all tasks have completed execution after a
      * shutdown request, or the timeout occurs, or the current thread
      * is interrupted, whichever happens first. Because the {@link
      * #commonPool()} never terminates until program shutdown, when
      * applied to the common pool, this method is equivalent to {@link
      * #awaitQuiescence} but always returns {@code false}.
      *
      * @param timeout the maximum time to wait
      * @param unit the time unit of the timeout argument
      * @return {@code true} if this executor terminated and
      *         {@code false} if the timeout elapsed before termination
      * @throws InterruptedException if interrupted while waiting
      */
     public boolean awaitTermination(long timeout, TimeUnit unit)