RFR: 8286983: rename jdb -trackvthreads and debug agent enumeratevthreads options and clarify "Preview Feature" nature of these options [v5]

[Alex Menkov]

On Tue, 31 May 2022 18:14:51 GMT, Chris Plummer <cjplummer at openjdk.org> wrote:

>> As part of the loom integration, jdb added `-trackvthreads` and the debug agent added `enumeratevthreads`. These options are being renamed to `-trackallthreads` and `includevirtualthreads` (the shorthand `vthreads` should not have been used). Also, the help text for these options now calls out that virtual threads are a Preview Feature.
>> 
>> After the update to help text, wlil look as follows:
>> 
>> jdb doc (search for "trackallthreads"): http://cr.openjdk.java.net/~cjplummer/8286983/jdb.html
>> debug agent doc (seach for "includevirtualthreads"): http://cr.openjdk.java.net/~cjplummer/8286983/conninv.html
>> 
>> 
>> $ jdb -listconnectors
>> ...
>>   Connector: com.sun.jdi.CommandLineLaunch  Transport: dt_socket
>>     description: Launches target using Sun Java VM command line and attaches to it
>> ...
>>     Argument: includevirtualthreads Default value: n
>>     description: List of all threads includes virtual threads as well as platform threads. Virtual threads are a preview feature of the Java platform.
>> 
>> 
>> 
>> $ jdb -help
>> Usage: jdb <options> <class> <arguments>
>> 
>> where options include:
>> ...
>>     -dbgtrace [flags] print info for debugging jdb
>>     -trackallthreads  Track all threads, including virtual threads.
>>                       Virtual threads are a preview feature of the Java platform.
>>     -tclient          run the application in the HotSpot(TM) Client Compiler
>> ...
>> 
>> 
>> 
>> $ man -M ./build/linux-x64-debug/images/jdk/man/ jdb
>> ...
>>        -tclient
>>               Runs the application in the Java HotSpot VM client.
>> 
>>        -trackallthreads
>>               Track  all  threads  as  they  are  created,  including  Virtual
>>               Threads.   See  Working  With  Virtual  Threads  below.  Virtual
>>               threads are a preview feature of the Java platform.
>> 
>>        -tserver
>>               Runs the application in the Java HotSpot VM server.
>> ...
>> WORKING WITH VIRTUAL THREADS
>>        Virtual threads are a preview feature of the  Java  platform.   Preview
>>        features  may  be removed in a future release, or upgraded to permanent
>>        features of the Java platform.
>> 
>>        Often virtual theads are created in such large  numbers  and  frequency
>> ...
>> 
>> 
>> 
>> $ java -agentlib:jdwp=help
>>                Java Debugger JDWP Agent Library
>>                --------------------------------
>> 
>>   (See the "VM Invocation Options" section of the JPDA
>>    "Connection and Invocation Details" document for more information.)
>> 
>> jdwp usage: java -agentlib:jdwp=[help]|[<option>=<value>, ...]
>> 
>> Option Name and Value            Description                       Default
>> ---------------------            -----------                       -------
>> ...
>> timeout=<timeout value>          for listen/attach in milliseconds n
>> includevirtualthreads=y|n        List of all threads includes virtual threads as well as platform threads.
>>                                  Virtual threads are a preview feature of the Java platform.
>>                                                                    n
>> mutf8=y|n                        output modified utf-8             n
>> ...
>
> Chris Plummer has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Don't capitalize "virtual threads"

src/jdk.jdi/share/classes/com/sun/tools/example/debug/tty/TTYResources.java line 479:

> 477:              "                      connect to target VM using named connector with listed argument values\n" +
> 478:              "    -dbgtrace [flags] print info for debugging {0}\n" +
> 479:              "    -trackallthreads  Track all threads, including virtual threads.\n" +

should this start from lower case letter for consistency?

src/jdk.jdwp.agent/share/native/libjdwp/debugInit.c line 880:

> 878:  "onuncaught=y|n                   debug on any uncaught?            n\n"
> 879:  "timeout=<timeout value>          for listen/attach in milliseconds n\n"
> 880:  "includevirtualthreads=y|n        List of all threads includes virtual threads as well as platform threads.\n"

start from lower case?

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

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