Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8173113

Javadoc for ThreadPoolExecutor is unclear wrt corePoolSize and running threads

    Details

      Description

      FULL PRODUCT VERSION :


      A DESCRIPTION OF THE PROBLEM :
      If you read the paragraph titled "Core and maximum pool sizes", it doesn't state what happens if the number of running threads is *equal to* corePoolSize.

      "[...]
      When a new task is submitted [...], and fewer than corePoolSize threads are running, a new thread is created to handle the request[...]. If there are more than corePoolSize but less than maximumPoolSize threads running, a new thread will be created only if the queue is full. [...]"

      As ThreadPoolExecutor's behaviour is already confusing for many developers, this documentation should be more precise.


      REPRODUCIBILITY :
      This bug can be reproduced always.

        Activity

        Show
        aroy Abhijit Roy (Inactive) added a comment - Link: JDK 7 : https://docs.oracle.com/javase/7/docs/api/java/util/concurrent/ThreadPoolExecutor.html JDK 8 : https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/ThreadPoolExecutor.html JDK 9 : http://download.java.net/java/jdk9/docs/api/java/util/concurrent/ThreadPoolExecutor.html
        Hide
        chegar Chris Hegarty added a comment -
        A minor spec clarification could be added that reflects current behavior.
        Show
        chegar Chris Hegarty added a comment - A minor spec clarification could be added that reflects current behavior.
        Hide
        dholmes David Holmes added a comment - - edited
        Okay:

        "When a new task is submitted in method execute(Runnable), and fewer than corePoolSize threads are running, a new thread is created to handle the request, even if other worker threads are idle. If there are more than corePoolSize but less than maximumPoolSize threads running, a new thread will be created only if the queue is full. "

        "more than corePoolSize" should be "more or equal to corePoolSize" - though not worded that clumsily.
        Show
        dholmes David Holmes added a comment - - edited Okay: "When a new task is submitted in method execute(Runnable), and fewer than corePoolSize threads are running, a new thread is created to handle the request, even if other worker threads are idle. If there are more than corePoolSize but less than maximumPoolSize threads running, a new thread will be created only if the queue is full. " "more than corePoolSize" should be "more or equal to corePoolSize" - though not worded that clumsily.
        Hide
        martin Martin Buchholz added a comment -
        We have the usual conflict between clarity and lawyerly precision.
        Show
        martin Martin Buchholz added a comment - We have the usual conflict between clarity and lawyerly precision.
        Hide
        martin Martin Buchholz added a comment -
        A small improvement seems to be:

        --- src/main/java/util/concurrent/ThreadPoolExecutor.java 19 Feb 2017 00:31:33 -0000 1.168
        +++ src/main/java/util/concurrent/ThreadPoolExecutor.java 19 Feb 2017 00:36:16 -0000
        @@ -52,18 +52,17 @@
          * maximumPoolSize (see {@link #getMaximumPoolSize}).
          *
          * When a new task is submitted in method {@link #execute(Runnable)},
        - * and fewer than corePoolSize threads are running, a new thread is
        + * if fewer than corePoolSize threads are running, a new thread is
          * created to handle the request, even if other worker threads are
        - * idle. If there are more than corePoolSize but less than
        - * maximumPoolSize threads running, a new thread will be created only
        - * if the queue is full. By setting corePoolSize and maximumPoolSize
        - * the same, you create a fixed-size thread pool. By setting
        - * maximumPoolSize to an essentially unbounded value such as {@code
        - * Integer.MAX_VALUE}, you allow the pool to accommodate an arbitrary
        - * number of concurrent tasks. Most typically, core and maximum pool
        - * sizes are set only upon construction, but they may also be changed
        - * dynamically using {@link #setCorePoolSize} and {@link
        - * #setMaximumPoolSize}. </dd>
        + * idle. Else if fewer than maximumPoolSize threads are running, a
        + * new thread will be created to handle the request only if the queue
        + * is full. By setting corePoolSize and maximumPoolSize the same, you
        + * create a fixed-size thread pool. By setting maximumPoolSize to an
        + * essentially unbounded value such as {@code Integer.MAX_VALUE}, you
        + * allow the pool to accommodate an arbitrary number of concurrent
        + * tasks. Most typically, core and maximum pool sizes are set only
        + * upon construction, but they may also be changed dynamically using
        + * {@link #setCorePoolSize} and {@link #setMaximumPoolSize}. </dd>
        Show
        martin Martin Buchholz added a comment - A small improvement seems to be: --- src/main/java/util/concurrent/ThreadPoolExecutor.java 19 Feb 2017 00:31:33 -0000 1.168 +++ src/main/java/util/concurrent/ThreadPoolExecutor.java 19 Feb 2017 00:36:16 -0000 @@ -52,18 +52,17 @@   * maximumPoolSize (see {@link #getMaximumPoolSize}).   *   * When a new task is submitted in method {@link #execute(Runnable)}, - * and fewer than corePoolSize threads are running, a new thread is + * if fewer than corePoolSize threads are running, a new thread is   * created to handle the request, even if other worker threads are - * idle. If there are more than corePoolSize but less than - * maximumPoolSize threads running, a new thread will be created only - * if the queue is full. By setting corePoolSize and maximumPoolSize - * the same, you create a fixed-size thread pool. By setting - * maximumPoolSize to an essentially unbounded value such as {@code - * Integer.MAX_VALUE}, you allow the pool to accommodate an arbitrary - * number of concurrent tasks. Most typically, core and maximum pool - * sizes are set only upon construction, but they may also be changed - * dynamically using {@link #setCorePoolSize} and {@link - * #setMaximumPoolSize}. </dd> + * idle. Else if fewer than maximumPoolSize threads are running, a + * new thread will be created to handle the request only if the queue + * is full. By setting corePoolSize and maximumPoolSize the same, you + * create a fixed-size thread pool. By setting maximumPoolSize to an + * essentially unbounded value such as {@code Integer.MAX_VALUE}, you + * allow the pool to accommodate an arbitrary number of concurrent + * tasks. Most typically, core and maximum pool sizes are set only + * upon construction, but they may also be changed dynamically using + * {@link #setCorePoolSize} and {@link #setMaximumPoolSize}. </dd>
        Hide
        hgupdate HG Updates added a comment -
        URL: http://hg.openjdk.java.net/jdk10/jdk10/jdk/rev/a2bee74ce5f6
        User: martin
        Date: 2017-07-22 17:50:20 +0000
        Show
        hgupdate HG Updates added a comment - URL: http://hg.openjdk.java.net/jdk10/jdk10/jdk/rev/a2bee74ce5f6 User: martin Date: 2017-07-22 17:50:20 +0000

          People

          • Assignee:
            martin Martin Buchholz
            Reporter:
            webbuggrp Webbug Group
          • Votes:
            0 Vote for this issue
            Watchers:
            7 Start watching this issue

            Dates

            • Created:
              Updated:
              Resolved: