JDK-8261543 : Adjust jmap -histo to accept "noparallel" option to inspect heap serially
  • Type: CSR
  • Component: core-svc
  • Sub-Component: tools
  • Priority: P4
  • Status: Closed
  • Resolution: Withdrawn
  • Submitted: 2021-02-11
  • Updated: 2021-02-17
  • Resolved: 2021-02-17
Related Reports
CSR :  
JDK-8261482 - Adjust jmap histo command to accept noparallel option to inspect heap serially
Description
Summary
-------
The current "jmap -histo" command accepts a parallel=[N] option to indicate the number of parallel threads, which exposes too much details to user and makes spec hard to be clear and not to be ambiguous.

Propose to enable parallel heap inspection by default and remove "parallel=[N]" option. Instead introduce a new option "noparallel" to allow user to do heap inspection non-parallel.


Specification
-------------
The change of jmap help info looks like:

    Usage:

    jmap -clstats <pid>
        to connect to running process and print class loader statistics
    jmap -finalizerinfo <pid>
        to connect to running process and print information on objects awaiting finalization
    jmap -histo[:[<histo-options>]] <pid>
        to connect to running process and print histogram of java object heap
    jmap -dump:<dump-options> <pid>
        to connect to running process and dump java heap
    jmap -? -h --help
        to print this help message

    dump-options:
      live         dump only live objects (takes precedence if both "live" and "all" are specified)
      all          dump all objects in the heap (default if one of "live" or "all" is not specified)
      format=b     binary format
      file=<file>  dump heap to <file>
      gz=<number>  If specified, the heap dump is written in gzipped format using the given compression level.
                   1 (recommended) is the fastest, 9 the strongest compression.

    Example: jmap -dump:live,format=b,file=heap.bin <pid>

    histo-options:
      live         count only live objects (takes precedence if both "live" and "all" are specified)
      all          count all objects in the heap (default if one of "live" or "all" is not specified)
      file=<file>  dump data to <file>
    - parallel=<number>  parallel threads number for heap iteration: 
    -                           parallel=0 default behavior, use predefined number of threads
    -                           parallel=1 disable parallel heap iteration
    -                           parallel=<N> use N threads for parallel heap iteration
    + noparallel   If specified, the heap is inspected serially.

    Example: jmap -histo:live,file=/tmp/histo.data <pid>
Comments
As discussed in https://github.com/openjdk/jdk/pull/2379, it is prefered to keep "parallel=n" option, and also extend a new command called heapdumpext. So I would like to close this CSR and create a new one for heapdumpext command.
17-02-2021
**`jmap -dump`** can't support a **`noparallel`** option, because that requires modifying the attach api **`dumpheap`** command to make room for a 4th argument, and that creates compatibility issues that are hard to resolve cleanly. I think **`jmap -dump`** and **`jmap -histo`** should be consistent in how they support parallelism, so that may mean not having any sort of parallel option for either, and just have parallelism always on by default. If the user wants to turn it off, they would need to use the **`GC.class_histogram`** or **`GC.heap_dump`** jcmds, which will support a **`noparallel`** option. If we have concerns about not being able to turn off parallel from the **`jmap`**, we may need to support doing that by having a new attach api command that is used to turn off parallel. This way the user can still specify **`jmap -dump:noparallel`**, but the underlying support would be implemented by first sending a **`noparallel`** command via the attach API, and not as a 4th argument to the **`dumpheap`** command. Having said all of this, I've been reminded of the suggestion (actually mine) to add a new attach api command called **`dumpheapext`**. It would be the same as **`dumpheap`** but allow for more arguments, thus solving the 4th argument issue. If using it returns an error (because of attaching to an incompatible JVM), then **`jmap -dump`** will resort to just using **`dumpheap`**. So with this approach both **`jmap -dump`** and **`jmap -histo`** can support **`noparallel`**.
12-02-2021