6620549: ExecutorService#shutdown should clearly state that it does not block

Reviewed-by: dholmes

jdk/src/share/classes/java/util/concurrent/ExecutorService.java

@@ -145,6 +145,10 @@ public interface ExecutorService extends Executor {
      * tasks are executed, but no new tasks will be accepted.
      * Invocation has no additional effect if already shut down.
      *
+     * <p>This method does not wait for previously submitted tasks to
+     * complete execution.  Use {@link #awaitTermination awaitTermination}
+     * to do that.
+     *
      * @throws SecurityException if a security manager exists and
      *         shutting down this ExecutorService may manipulate
      *         threads that the caller is not permitted to modify
@@ -157,8 +161,12 @@ public interface ExecutorService extends Executor {
 
     /**
      * Attempts to stop all actively executing tasks, halts the
-     * processing of waiting tasks, and returns a list of the tasks that were
+     * processing of waiting tasks, and returns a list of the tasks
-     * awaiting execution.
+     * that were awaiting execution.
+     *
+     * <p>This method does not wait for actively executing tasks to
+     * terminate.  Use {@link #awaitTermination awaitTermination} to
+     * do that.
      *
      * <p>There are no guarantees beyond best-effort attempts to stop
      * processing actively executing tasks.  For example, typical

jdk/src/share/classes/java/util/concurrent/ScheduledThreadPoolExecutor.java

@@ -702,13 +702,19 @@ public class ScheduledThreadPoolExecutor
 
     /**
      * Initiates an orderly shutdown in which previously submitted
-     * tasks are executed, but no new tasks will be accepted.  If the
+     * tasks are executed, but no new tasks will be accepted.
-     * {@code ExecuteExistingDelayedTasksAfterShutdownPolicy} has
+     * Invocation has no additional effect if already shut down.
-     * been set {@code false}, existing delayed tasks whose delays
+     *
-     * have not yet elapsed are cancelled.  And unless the
+     * <p>This method does not wait for previously submitted tasks to
-     * {@code ContinueExistingPeriodicTasksAfterShutdownPolicy} has
+     * complete execution.  Use {@link #awaitTermination awaitTermination}
-     * been set {@code true}, future executions of existing periodic
+     * to do that.
-     * tasks will be cancelled.
+     *
+     * <p>If the {@code ExecuteExistingDelayedTasksAfterShutdownPolicy}
+     * has been set {@code false}, existing delayed tasks whose delays
+     * have not yet elapsed are cancelled.  And unless the {@code
+     * ContinueExistingPeriodicTasksAfterShutdownPolicy} has been set
+     * {@code true}, future executions of existing periodic tasks will
+     * be cancelled.
      *
      * @throws SecurityException {@inheritDoc}
      */
@@ -721,6 +727,10 @@ public class ScheduledThreadPoolExecutor
      * processing of waiting tasks, and returns a list of the tasks
      * that were awaiting execution.
      *
+     * <p>This method does not wait for actively executing tasks to
+     * terminate.  Use {@link #awaitTermination awaitTermination} to
+     * do that.
+     *
      * <p>There are no guarantees beyond best-effort attempts to stop
      * processing actively executing tasks.  This implementation
      * cancels tasks via {@link Thread#interrupt}, so any task that

jdk/src/share/classes/java/util/concurrent/ThreadPoolExecutor.java

@@ -1342,6 +1342,10 @@ public class ThreadPoolExecutor extends AbstractExecutorService {
      * tasks are executed, but no new tasks will be accepted.
      * Invocation has no additional effect if already shut down.
      *
+     * <p>This method does not wait for previously submitted tasks to
+     * complete execution.  Use {@link #awaitTermination awaitTermination}
+     * to do that.
+     *
      * @throws SecurityException {@inheritDoc}
      */
     public void shutdown() {
@@ -1364,6 +1368,10 @@ public class ThreadPoolExecutor extends AbstractExecutorService {
      * that were awaiting execution. These tasks are drained (removed)
      * from the task queue upon return from this method.
      *
+     * <p>This method does not wait for actively executing tasks to
+     * terminate.  Use {@link #awaitTermination awaitTermination} to
+     * do that.
+     *
      * <p>There are no guarantees beyond best-effort attempts to stop
      * processing actively executing tasks.  This implementation
      * cancels tasks via {@link Thread#interrupt}, so any task that