This is an automated email from the ASF dual-hosted git repository.

markt pushed a commit to branch 11.0.x
in repository https://gitbox.apache.org/repos/asf/tomcat.git


The following commit(s) were added to refs/heads/11.0.x by this push:
     new 4562c2e059 Javadoc updates in preparation for applying automatic 
formatting
4562c2e059 is described below

commit 4562c2e059e5a3a93fa6d29f7a0664b2648a7d74
Author: Mark Thomas <ma...@apache.org>
AuthorDate: Thu Aug 28 11:01:32 2025 +0100

    Javadoc updates in preparation for applying automatic formatting
---
 .../tomcat/util/threads/ThreadPoolExecutor.java    | 100 +++++++++++----------
 1 file changed, 52 insertions(+), 48 deletions(-)

diff --git a/java/org/apache/tomcat/util/threads/ThreadPoolExecutor.java 
b/java/org/apache/tomcat/util/threads/ThreadPoolExecutor.java
index c32769a1e0..3248a4c389 100644
--- a/java/org/apache/tomcat/util/threads/ThreadPoolExecutor.java
+++ b/java/org/apache/tomcat/util/threads/ThreadPoolExecutor.java
@@ -333,17 +333,18 @@ public class ThreadPoolExecutor extends 
AbstractExecutorService {
 
     /**
      * The main pool control state, ctl, is an atomic integer packing
-     * two conceptual fields
-     *   workerCount, indicating the effective number of threads
-     *   runState,    indicating whether running, shutting down etc
-     *
+     * two conceptual fields:
+     * <ul>
+     *   <li>workerCount, indicating the effective number of threads</li>
+     *   <li>runState,    indicating whether running, shutting down etc</li>
+     * </ul>
      * In order to pack them into one int, we limit workerCount to
      * (2^29)-1 (about 500 million) threads rather than (2^31)-1 (2
      * billion) otherwise representable. If this is ever an issue in
      * the future, the variable can be changed to be an AtomicLong,
      * and the shift/mask constants below adjusted. But until the need
      * arises, this code is a bit faster and simpler using an int.
-     *
+     * <p>
      * The workerCount is the number of workers that have been
      * permitted to start and not permitted to stop.  The value may be
      * transiently different from the actual number of live threads,
@@ -351,36 +352,36 @@ public class ThreadPoolExecutor extends 
AbstractExecutorService {
      * asked, and when exiting threads are still performing
      * bookkeeping before terminating. The user-visible pool size is
      * reported as the current size of the workers set.
-     *
+     * <p>
      * The runState provides the main lifecycle control, taking on values:
-     *
-     *   RUNNING:  Accept new tasks and process queued tasks
-     *   SHUTDOWN: Don't accept new tasks, but process queued tasks
-     *   STOP:     Don't accept new tasks, don't process queued tasks,
-     *             and interrupt in-progress tasks
-     *   TIDYING:  All tasks have terminated, workerCount is zero,
+     * <ul>
+     *   <li>RUNNING:  Accept new tasks and process queued tasks</li>
+     *   <li>SHUTDOWN: Don't accept new tasks, but process queued tasks</li>
+     *   <li>STOP:     Don't accept new tasks, don't process queued tasks,
+     *             and interrupt in-progress tasks</li>
+     *   <li>TIDYING:  All tasks have terminated, workerCount is zero,
      *             the thread transitioning to state TIDYING
-     *             will run the terminated() hook method
-     *   TERMINATED: terminated() has completed
-     *
+     *             will run the terminated() hook method</li>
+     *   <li>TERMINATED: terminated() has completed</li>
+     * </ul>
      * The numerical order among these values matters, to allow
      * ordered comparisons. The runState monotonically increases over
      * time, but need not hit each state. The transitions are:
-     *
-     * RUNNING -> SHUTDOWN
-     *    On invocation of shutdown()
-     * (RUNNING or SHUTDOWN) -> STOP
-     *    On invocation of shutdownNow()
-     * SHUTDOWN -> TIDYING
-     *    When both queue and pool are empty
-     * STOP -> TIDYING
-     *    When pool is empty
-     * TIDYING -> TERMINATED
-     *    When the terminated() hook method has completed
-     *
+     * <ul>
+     * <li>RUNNING -> SHUTDOWN
+     *    On invocation of shutdown()</li>
+     * <li>(RUNNING or SHUTDOWN) -> STOP
+     *    On invocation of shutdownNow()</li>
+     * <li>SHUTDOWN -> TIDYING
+     *    When both queue and pool are empty</li>
+     * <li>STOP -> TIDYING
+     *    When pool is empty</li>
+     * <li>TIDYING -> TERMINATED
+     *    When the terminated() hook method has completed</li>
+     * </ul>
      * Threads waiting in awaitTermination() will return when the
      * state reaches TERMINATED.
-     *
+     * <p>
      * Detecting the transition from SHUTDOWN to TIDYING is less
      * straightforward than you'd like because the queue may become
      * empty after non-empty and vice versa during SHUTDOWN state, but
@@ -530,7 +531,7 @@ public class ThreadPoolExecutor extends 
AbstractExecutorService {
      * treated as an error, failure to create threads may result in
      * new tasks being rejected or existing ones remaining stuck in
      * the queue.
-     *
+     * <p>
      * We go further and preserve pool invariants even in the face of
      * errors such as OutOfMemoryError, that might be thrown while
      * trying to create threads.  Such errors are rather common due to
@@ -565,7 +566,7 @@ public class ThreadPoolExecutor extends 
AbstractExecutorService {
      * Core pool size is the minimum number of workers to keep alive
      * (and not allow to time out etc) unless allowCoreThreadTimeOut
      * is set, in which case the minimum is zero.
-     *
+     * <p>
      * Since the worker count is actually stored in COUNT_BITS bits,
      * the effective limit is {@code corePoolSize & COUNT_MASK}.
      */
@@ -573,7 +574,7 @@ public class ThreadPoolExecutor extends 
AbstractExecutorService {
 
     /**
      * Maximum pool size.
-     *
+     * <p>
      * Since the worker count is actually stored in COUNT_BITS bits,
      * the effective limit is {@code maximumPoolSize & COUNT_MASK}.
      */
@@ -954,10 +955,12 @@ public class ThreadPoolExecutor extends 
AbstractExecutorService {
 
     /**
      * Rolls back the worker thread creation.
-     * - removes worker from workers, if present
-     * - decrements worker count
-     * - rechecks for termination, in case the existence of this
-     *   worker was holding up termination
+     * <ul>
+     * <li>removes worker from workers, if present</li>
+     * <li>decrements worker count</li>
+     * <li>rechecks for termination, in case the existence of this
+     *   worker was holding up termination</li>
+     * </ul>
      */
     private void addWorkerFailed(Worker w) {
         final ReentrantLock mainLock = this.mainLock;
@@ -1028,16 +1031,17 @@ public class ThreadPoolExecutor extends 
AbstractExecutorService {
      * Performs blocking or timed wait for a task, depending on
      * current configuration settings, or returns null if this worker
      * must exit because of any of:
-     * 1. There are more than maximumPoolSize workers (due to
-     *    a call to setMaximumPoolSize).
-     * 2. The pool is stopped.
-     * 3. The pool is shutdown and the queue is empty.
-     * 4. This worker timed out waiting for a task, and timed-out
+     * <ol>
+     * <li>There are more than maximumPoolSize workers (due to
+     *    a call to setMaximumPoolSize).</li>
+     * <li>The pool is stopped.</li>
+     * <li>The pool is shutdown and the queue is empty.</li>
+     * <li>This worker timed out waiting for a task, and timed-out
      *    workers are subject to termination (that is,
      *    {@code allowCoreThreadTimeOut || workerCount > corePoolSize})
      *    both before and after the timed wait, and if the queue is
-     *    non-empty, this worker is not the last thread in the pool.
-     *
+     *    non-empty, this worker is not the last thread in the pool.</li>
+     * </ol>
      * @return task, or null if the worker must exit, in which case
      *         workerCount is decremented
      */
@@ -1084,7 +1088,7 @@ public class ThreadPoolExecutor extends 
AbstractExecutorService {
     /**
      * Main worker run loop.  Repeatedly gets tasks from queue and
      * executes them, while coping with a number of issues:
-     *
+     * <p>
      * 1. We may start out with an initial task, in which case we
      * don't need to get the first one. Otherwise, as long as pool is
      * running, we get tasks from getTask. If it returns null then the
@@ -1092,17 +1096,17 @@ public class ThreadPoolExecutor extends 
AbstractExecutorService {
      * parameters.  Other exits result from exception throws in
      * external code, in which case completedAbruptly holds, which
      * usually leads processWorkerExit to replace this thread.
-     *
+     * <p>
      * 2. Before running any task, the lock is acquired to prevent
      * other pool interrupts while the task is executing, and then we
      * ensure that unless pool is stopping, this thread does not have
      * its interrupt set.
-     *
+     * <p>
      * 3. Each task run is preceded by a call to beforeExecute, which
      * might throw an exception, in which case we cause thread to die
      * (breaking loop with completedAbruptly true) without processing
      * the task.
-     *
+     * <p>
      * 4. Assuming beforeExecute completes normally, we run the task,
      * gathering any of its thrown exceptions to send to afterExecute.
      * We separately handle RuntimeException, Error (both of which the
@@ -1111,12 +1115,12 @@ public class ThreadPoolExecutor extends 
AbstractExecutorService {
      * wrap them within Errors on the way out (to the thread's
      * UncaughtExceptionHandler).  Any thrown exception also
      * conservatively causes thread to die.
-     *
+     * <p>
      * 5. After task.run completes, we call afterExecute, which may
      * also throw an exception, which will also cause thread to
      * die. According to JLS Sec 14.20, this exception is the one that
      * will be in effect even if task.run throws.
-     *
+     * <p>
      * The net effect of the exception mechanics is that afterExecute
      * and the thread's UncaughtExceptionHandler have as accurate
      * information as we can provide about any problems encountered by


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@tomcat.apache.org
For additional commands, e-mail: dev-h...@tomcat.apache.org

Reply via email to