RFR: JDK-8261034: improve jcmd GC.class_histogram to support parallel

[Chris Plummer]

On Sat, 20 Feb 2021 00:47:56 GMT, Hamlin Li <mli at openjdk.org> wrote:

>> BTW, we have three PRs related to `parallel=<n>`. I think it would be best to hold off pushing any of them until they have all been reviewed and approved. One reason is because the `parallel=<n>` output should be consistent for all of them, and if there is a minor suggestion for a change in one, it should be applied to all 3.
>
>> BTW, we have three PRs related to `parallel=<n>`. I think it would be best to hold off pushing any of them until they have all been reviewed and approved. One reason is because the `parallel=<n>` output should be consistent for all of them, and if there is a minor suggestion for a change in one, it should be applied to all 3.
> 
> Sure, will hold off.
> Summarize the help messages as below:
> "Number of parallel threads to use for heap inspection. "
> "0: let the VM determine the number of threads to use. "
> "1: use one thread, i.e. disable parallelism. "
> "n: Request that threads be used. n must be positive. The VM will try to use n threads, but might use fewer threads than n."

For jmap -histo we have:

      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

It's a bit inconsistent here in that it says <number>, <N>, and N. I'd like to see that cleaned up at some point along with a few other things (as part of a separate PR). However, my point is that the value of the argument is given a name, <number> in this case, so it can be referenced in the help output. However, jmap help is done differently than jcmd help, which doesn't give names to the value of options. For example, GC.heap_dump has:

Options: (options must be specified using the <key> or <key>=<value> syntax)
	-all : [optional] Dump all objects, including unreachable objects (BOOLEAN, false)
	-gz : [optional] If specified, the heap dump is written in gzipped format using the given compression level. 1 (recommended) is the fastest, 9 the strongest compression. (INT, 1)

The -gz option is much like -parallel in that a value is given for it, but there is no "name" for that value in the help output. So maybe we should avoid calling it "n" or <n>, or anything like that:

"Number of parallel threads to use for heap inspection."
"0 (the default) means let the VM determine the number of threads to use. "
"1 means use one thread (disable parallelism). "
"For any other value the VM will try to use the specified number of threads, but might use fewer."

I think we can leave out "Must be positive." It should be obvious, and I assume an error is generated if negative number is given.

-------------

PR: https://git.openjdk.java.net/jdk/pull/2379