Improve javadoc

Author: AlanBateman

src/java.base/share/classes/java/util/concurrent/Executors.java

@@ -240,13 +240,12 @@ public static ExecutorService newCachedThreadPool(ThreadFactory threadFactory) {
     }
 
     /**
-     * Creates an Executor that starts a new Thread for each task. The Executor
-     * is <i>owned</i> by the Thread that creates it.
+     * Creates an Executor that starts a new Thread for each task.
      *
      * <p> An Executor created by this method is intended to be used in a
      * <em>structured manner</em>. It is <em>owned</em> by the Thread that creates
-     * it and must be {@linkplain ExecutorService#close() closed} by the thread
-     * when it is finished with the executor. Failure to invoke the {@code
+     * it and must be {@linkplain ExecutorService#close() closed} by the same
+     * thread when it is finished with the executor. Failure to invoke the {@code
      * close} method may result in a memory leak. The {@code close}, {@link
      * ExecutorService#shutdown() shutdown}, and {@link ExecutorService#shutdownNow()
      * shutdownNow} methods throw {@code IllegalCallerException} if invoked by
@@ -260,7 +259,8 @@ public static ExecutorService newCachedThreadPool(ThreadFactory threadFactory) {
      *
      * <p> Invoking {@link Future#cancel(boolean) cancel(true)} on a {@link
      * Future Future} representing the pending result of a task submitted to
-     * the Executor will {@link Thread#interrupt() interrupt} the thread.
+     * the Executor will {@link Thread#interrupt() interrupt} the thread
+     * executing the task.
      *
      * @apiNote
      * The {@link #newUnownedThreadExecutor(ThreadFactory)} method should be
@@ -272,21 +272,37 @@ public static ExecutorService newCachedThreadPool(ThreadFactory threadFactory) {
      * @since 99
      */
     public static ExecutorService newThreadExecutor(ThreadFactory threadFactory) {
-        return new ThreadExecutor(threadFactory, null, false);
+        return new ThreadExecutor(threadFactory, null, true);
     }
 
     /**
-     * Creates an Executor that starts a new Thread for each task. The Executor
-     * is <i>owned</i> by the Thread that creates it.
-     *
-     * The Executor is created with a deadline. If the deadline is reached before
-     * the Executor has terminated then it is {@link ExecutorService#shutdown()
-     * shutdown} and its threads are {@linkplain Thread#interrupt() interrupted}
-     * to cancel the remaining tasks.
-     * If this method is invoked with a deadline that has already expired then
-     * it returns an Executor that is already shutdown (any attempt to submit
+     * Creates an Executor that starts a new Thread for each task and with a
+     * deadline. If the deadline is reached before the Executor has terminated
+     * then it is {@link ExecutorService#shutdown() shutdown} and its threads
+     * are {@linkplain Thread#interrupt() interrupted} to cancel the remaining
+     * tasks. If this method is invoked with a deadline that has already expired
+     * then it returns an Executor that is already shutdown (any attempt to submit
      * a task will fail with {@code RejectedExecutionException}).
      *
+     * <p> An Executor created by this method is intended to be used in a
+     * <em>structured manner</em>. It is <em>owned</em> by the Thread that creates
+     * it and must be {@linkplain ExecutorService#close() closed} by the same
+     * thread when it is finished with the executor. Failure to invoke the {@code
+     * close} method may result in a memory leak. The {@code close}, {@code
+     * shutdown} and {@link ExecutorService#shutdownNow() shutdownNow} methods
+     * throw {@code IllegalCallerException} if invoked by other threads.
+     * Executors created by this method enforce strict nesting and must be
+     * closed in the reverse order that they are created in. The {@code close}
+     * method throws {@code IllegalStateException} if invoked to close
+     * executors created by this method in a different order. Once closed by
+     * its owner, further attempts to close the executor by its owner has no
+     * effect.
+     *
+     * <p> Invoking {@link Future#cancel(boolean) cancel(true)} on a {@link
+     * Future Future} representing the pending result of a task submitted to
+     * the Executor will {@link Thread#interrupt() interrupt} the thread
+     * executing the task.
+     *
      * @param threadFactory the factory to use when creating new threads
      * @param deadline the deadline
      * @return a newly created executor
@@ -295,14 +311,12 @@ public static ExecutorService newThreadExecutor(ThreadFactory threadFactory) {
      */
     public static ExecutorService newThreadExecutor(ThreadFactory threadFactory,
                                                     Instant deadline) {
-        Objects.requireNonNull(threadFactory);
         Objects.requireNonNull(deadline);
-        return new ThreadExecutor(threadFactory, deadline, false);
+        return new ThreadExecutor(threadFactory, deadline, true);
     }
 
     /**
-     * Creates an Executor that starts a new virtual Thread for each task. The
-     * Executor is <i>owned</i> by the Thread that creates it.
+     * Creates an Executor that starts a new virtual Thread for each task.
      *
      * <p> This method is equivalent to creating an Executor with the {@link
      * #newThreadExecutor(ThreadFactory)} method and specifying a ThreadFactory
@@ -313,12 +327,12 @@ public static ExecutorService newThreadExecutor(ThreadFactory threadFactory,
      */
     public static ExecutorService newVirtualThreadExecutor() {
         ThreadFactory factory = Thread.ofVirtual().factory();
-        return new ThreadExecutor(factory, null, false);
+        return new ThreadExecutor(factory, null, true);
     }
 
     /**
-     * Creates an Executor that starts a new virtual Thread for each task. The
-     * Executor is <i>owned</i> by the Thread that creates it.
+     * Creates an Executor that starts a new virtual Thread for each task and
+     * with a deadline.
      *
      * <p> This method is equivalent to creating an Executor with the {@link
      * #newThreadExecutor(ThreadFactory, Instant)} method and specifying a
@@ -332,15 +346,21 @@ public static ExecutorService newVirtualThreadExecutor() {
     public static ExecutorService newVirtualThreadExecutor(Instant deadline) {
         Objects.requireNonNull(deadline);
         ThreadFactory factory = Thread.ofVirtual().factory();
-        return new ThreadExecutor(factory, deadline, false);
+        return new ThreadExecutor(factory, deadline, true);
     }
 
     /**
      * Creates an Executor that starts a new thread for each task.
      *
-     * The resulting Executor is not owned to any thread, meaning any thread can
-     * {@link ExecutorService#shutdown() shutdown} the Executor or invoke {@link
-     * ExecutorService#close() close} if they have the appropriate permission.
+     * <p> Unlike {@link #newThreadExecutor(ThreadFactory)}, the Executor is not
+     * owned by any thread so any thread can {@link ExecutorService#shutdown()
+     * shutdown} the Executor or invoke {@link ExecutorService#close() close}
+     * if they have the appropriate permission.
+     *
+     * <p> Invoking {@link Future#cancel(boolean) cancel(true)} on a {@link
+     * Future Future} representing the pending result of a task submitted to
+     * the Executor will {@link Thread#interrupt() interrupt} the thread
+     * executing the task.
      *
      * @apiNote
      * This method is intended for unstructured usage such as cases where an
@@ -353,7 +373,7 @@ public static ExecutorService newVirtualThreadExecutor(Instant deadline) {
      * @since 99
      */
     public static ExecutorService newUnownedThreadExecutor(ThreadFactory threadFactory) {
-        return new ThreadExecutor(threadFactory, null, true);
+        return new ThreadExecutor(threadFactory, null, false);
     }
 
     /**

src/java.base/share/classes/java/util/concurrent/ThreadExecutor.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2019, 2020, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2019, 2021, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -44,7 +44,6 @@
 import jdk.internal.misc.InnocuousThread;
 import static java.util.concurrent.TimeUnit.NANOSECONDS;
 
-
 /**
  * An ExecutorService that executes each task in its own thread.
  */
@@ -85,9 +84,9 @@ class ThreadExecutor implements ExecutorService {
      *
      * @param factory the thread factory
      * @param deadline the deadline, null for no deadline
-     * @param shared true if not owned by the caller thread
+     * @param owned true if owned by the caller thread
      */
-    ThreadExecutor(ThreadFactory factory, Instant deadline, boolean shared) {
+    ThreadExecutor(ThreadFactory factory, Instant deadline, boolean owned) {
         Objects.requireNonNull(factory);
         Future<?> timer = null;
         if (deadline != null) {
@@ -103,14 +102,14 @@ class ThreadExecutor implements ExecutorService {
 
         this.factory = factory;
         this.timerTask = timer;
-        if (shared) {
-            this.owner = null;
-            this.previous = null;
-        } else {
+        if (owned) {
             Thread owner = Thread.currentThread();
             this.owner = owner;
             this.previous = ThreadFields.latestThreadExecutor(owner);
             ThreadFields.setLatestThreadExecutor(this);
+        } else {
+            this.owner = null;
+            this.previous = null;
         }
     }