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

[Serguei Spitsyn]

On Sat, 20 Feb 2021 09:50:05 GMT, Hamlin Li <mli at openjdk.org> wrote:

>> 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.
>
> Sure, thanks for the detailed reviewing.
> Let me record the help message as below:
>     "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."

"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 like this approach - good idea.

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

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