United StatesChange Country, Oracle Worldwide Web Sites Communities I am a... I want to...
Bug ID: JDK-6979444 add command line option to print command line flags descriptions
JDK-6979444 : add command line option to print command line flags descriptions

Details
Type:
Enhancement
Submit Date:
2010-08-24
Status:
Closed
Updated Date:
2011-04-23
Project Name:
JDK
Resolved Date:
2011-04-23
Component:
hotspot
OS:
generic
Sub-Component:
runtime
CPU:
generic
Priority:
P4
Resolution:
Fixed
Affected Versions:
hs19
Fixed Versions:
hs19 (b07)

Related Reports
Backport:
Backport:
Backport:

Sub Tasks

Description
Here is a proposal to add printing of description of command line flags.
These descriptions are present in sources but they are not passed to the Flag structure.

There is an existing flag "-Xprintflags" that prints all flags and the default values.
This proposal extands that feature.

Here is a sample output of the proposed flag (formatting may go wrong below because of word wrapping)

java  -server  -XprintFlagsWithComments
[Global flags]
ccstr AbortVMOnException                   =  {notproduct}   Call fatal if this exception is thrown.  Example: java -XX:AbortVMOnExcepion=java.lang.NullPointerException Foo
ccstr AbortVMOnExceptionMessage            =  {notproduct}   Call fatal if the exception pointed by AbortVMOnException has this messag.
uintx AdaptivePermSizeWeight               = 20               {product}   Weight for perm gen exponential resizing, between 0 and 100
uintx AdaptiveSizeDecrementScaleFactor     = 4                {product}   Adaptive size scale down factor for shrinking
uintx AdaptiveSizeMajorGCDecayTimeScale    = 10               {product}   Time scale over which major costs decay
uintx AdaptiveSizePausePolicy              = 0                {product}   Policy for changing generation size for pause goals
uintx AdaptiveSizePolicyCollectionCostMargin  = 50               {product}   If collection costs are within margin, reduce both by ful delta
uintx AdaptiveSizePolicyGCTimeLimitThreshold  = 5                   Number of consecutive collections before gc time limit fires
uintx AdaptiveSizePolicyInitializingSteps  = 20               {product}   Number of steps where heuristics is used before data is used
uintx AdaptiveSizePolicyOutputInterval     = 0                {product}   Collecton interval for printing information; zero => never
uintx AdaptiveSizePolicyReadyThreshold     = 5                   Number of collections before the adaptive sizing is started
uintx AdaptiveSizePolicyWeight             = 10               {product}   Weight given to exponential resizing, between 0 and 100
uintx AdaptiveSizeThroughPutPolicy         = 0                {product}   Policy for changeing generation size for throughput goals
uintx AdaptiveTimeWeight                   = 25               {product}   Weight given to time in adaptive policy, between 0 and 100
 bool AdjustConcurrency                    = false            {product}   call thr_setconcurrency at thread create time to avoid LWP sarvation on MP systems (For Solaris Only)
 bool AggressiveOpts                       = false            {product}   Enable aggressive optimizations - see arguments.cpp
 intx AliasLevel                           = 3                {product}   0 for no aliasing, 1 for oop/field/static/array split, 2 forclass split, 3 for unique instances
 intx AlignEntryCode                       = 4                   aligns entry code to specified value (in bytes)
 intx AllocatePrefetchDistance             = -1               {product}   Distance to prefetch ahead of allocation pointer
.......

                                    

Comments
SUGGESTED FIX

Proposed flag name: -XprintFlagsWithComments

Patch file is provided below. If feature is approved - a formal webrev shall be sent.

--- old/src/share/vm/runtime/arguments.cpp	Tue Aug 24 10:17:08 2010
+++ new/src/share/vm/runtime/arguments.cpp	Tue Aug 24 10:17:06 2010
@@ -2211,9 +2211,13 @@
                   VM_Version::internal_vm_info_string());
       vm_exit(0);
 #ifndef PRODUCT
+    // -XprintFlagsWithComments
+    } else if (match_option(option, "-XprintFlagsWithComments", &tail)) {
+      CommandLineFlags::printFlags(true);
+      vm_exit(0);
     // -Xprintflags
     } else if (match_option(option, "-Xprintflags", &tail)) {
-      CommandLineFlags::printFlags();
+      CommandLineFlags::printFlags(false);
       vm_exit(0);
 #endif
     // -D
@@ -2827,7 +2831,7 @@
       IgnoreUnrecognizedVMOptions = false;
     }
     if (match_option(option, "-XX:+PrintFlagsInitial", &tail)) {
-      CommandLineFlags::printFlags();
+      CommandLineFlags::printFlags(false);
       vm_exit(0);
     }
   }
@@ -3004,7 +3008,7 @@
   }
 
   if (PrintFlagsFinal) {
-    CommandLineFlags::printFlags();
+    CommandLineFlags::printFlags(false);
   }
 
   // Apply CPU specific policy for the BiasedLocking
--- old/src/share/vm/runtime/globals.cpp	Tue Aug 24 10:17:14 2010
+++ new/src/share/vm/runtime/globals.cpp	Tue Aug 24 10:17:12 2010
@@ -68,30 +68,34 @@
 // Length of format string (e.g. "%.1234s") for printing ccstr below
 #define FORMAT_BUFFER_LEN 16
 
-void Flag::print_on(outputStream* st) {
-  st->print("%5s %-35s %c= ", type, name, (origin != DEFAULT ? ':' : ' '));
+void Flag::print_on(outputStream* st, bool withCommets) {
+  st->print("%5s %-40s %c= ", type, name, (origin != DEFAULT ? ':' : ' '));
   if (is_bool())     st->print("%-16s", get_bool() ? "true" : "false");
   if (is_intx())     st->print("%-16ld", get_intx());
   if (is_uintx())    st->print("%-16lu", get_uintx());
   if (is_uint64_t()) st->print("%-16lu", get_uint64_t());
+  if (is_double())   st->print("%-16f", get_double());
+
   if (is_ccstr()) {
-    const char* cp = get_ccstr();
-    if (cp != NULL) {
-      const char* eol;
-      while ((eol = strchr(cp, '\n')) != NULL) {
-        char format_buffer[FORMAT_BUFFER_LEN];
-        size_t llen = pointer_delta(eol, cp, sizeof(char));
-        jio_snprintf(format_buffer, FORMAT_BUFFER_LEN,
+     const char* cp = get_ccstr();
+     if (cp != NULL) {
+       const char* eol;
+       while ((eol = strchr(cp, '\n')) != NULL) {
+         char format_buffer[FORMAT_BUFFER_LEN];
+         size_t llen = pointer_delta(eol, cp, sizeof(char));
+         jio_snprintf(format_buffer, FORMAT_BUFFER_LEN,
                      "%%." SIZE_FORMAT "s", llen);
-        st->print(format_buffer, cp);
-        st->cr();
-        cp = eol+1;
-        st->print("%5s %-35s += ", "", name);
-      }
-      st->print("%-16s", cp);
-    }
+         st->print(format_buffer, cp);
+         st->cr();
+         cp = eol+1;
+         st->print("%5s %-35s += ", "", name);
+       }
+       st->print("%-16s", cp);
+     } 
+     else st->print("%-16s", "");
   }
-  st->print(" %s", kind);
+  st->print("%-20s", kind);
+  if (withCommets) st->print("%s", doc);
   st->cr();
 }
 
@@ -128,15 +132,23 @@
   }
 }
 
+// 6979444 Following define adds description of a flag in a NONPRODUCT mode
+
+#ifdef PRODUCT
+#define NON_PRODUCT_STRING(str) ""
+#else
+#define NON_PRODUCT_STRING(str) str
+#endif
+
 // 4991491 do not "optimize out" the was_set false values: omitting them
 // tickles a Microsoft compiler bug causing flagTable to be malformed
 
-#define RUNTIME_PRODUCT_FLAG_STRUCT(type, name, value, doc) { #type, XSTR(name), &name, "{product}", DEFAULT },
-#define RUNTIME_PD_PRODUCT_FLAG_STRUCT(type, name, doc)     { #type, XSTR(name), &name, "{pd product}", DEFAULT },
-#define RUNTIME_DIAGNOSTIC_FLAG_STRUCT(type, name, value, doc) { #type, XSTR(name), &name, "{diagnostic}", DEFAULT },
-#define RUNTIME_EXPERIMENTAL_FLAG_STRUCT(type, name, value, doc) { #type, XSTR(name), &name, "{experimental}", DEFAULT },
-#define RUNTIME_MANAGEABLE_FLAG_STRUCT(type, name, value, doc) { #type, XSTR(name), &name, "{manageable}", DEFAULT },
-#define RUNTIME_PRODUCT_RW_FLAG_STRUCT(type, name, value, doc) { #type, XSTR(name), &name, "{product rw}", DEFAULT },
+#define RUNTIME_PRODUCT_FLAG_STRUCT(type, name, value, doc) { #type, XSTR(name), &name, NON_PRODUCT_STRING(doc), "{product}", DEFAULT },
+#define RUNTIME_PD_PRODUCT_FLAG_STRUCT(type, name, doc)     { #type, XSTR(name), &name, NON_PRODUCT_STRING(doc), "{pd product}", DEFAULT },
+#define RUNTIME_DIAGNOSTIC_FLAG_STRUCT(type, name, value, doc) { #type, XSTR(name), &name, NON_PRODUCT_STRING(doc), "{diagnostic}", DEFAULT },
+#define RUNTIME_EXPERIMENTAL_FLAG_STRUCT(type, name, value, doc) { #type, XSTR(name), &name, NON_PRODUCT_STRING(doc), "{experimental}", DEFAULT },
+#define RUNTIME_MANAGEABLE_FLAG_STRUCT(type, name, value, doc) { #type, XSTR(name), &name, NON_PRODUCT_STRING(doc), "{manageable}", DEFAULT },
+#define RUNTIME_PRODUCT_RW_FLAG_STRUCT(type, name, value, doc) { #type, XSTR(name), &name, NON_PRODUCT_STRING(doc), "{product rw}", DEFAULT },
 
 #ifdef PRODUCT
   #define RUNTIME_DEVELOP_FLAG_STRUCT(type, name, value, doc) /* flag is constant */
@@ -143,55 +155,55 @@
   #define RUNTIME_PD_DEVELOP_FLAG_STRUCT(type, name, doc)     /* flag is constant */
   #define RUNTIME_NOTPRODUCT_FLAG_STRUCT(type, name, value, doc)
 #else
-  #define RUNTIME_DEVELOP_FLAG_STRUCT(type, name, value, doc) { #type, XSTR(name), &name, "", DEFAULT },
-  #define RUNTIME_PD_DEVELOP_FLAG_STRUCT(type, name, doc)     { #type, XSTR(name), &name, "{pd}", DEFAULT },
-  #define RUNTIME_NOTPRODUCT_FLAG_STRUCT(type, name, value, doc) { #type, XSTR(name), &name, "{notproduct}", DEFAULT },
+  #define RUNTIME_DEVELOP_FLAG_STRUCT(type, name, value, doc) { #type, XSTR(name), &name, doc, "", DEFAULT },
+  #define RUNTIME_PD_DEVELOP_FLAG_STRUCT(type, name, doc)     { #type, XSTR(name), &name, doc, "{pd}", DEFAULT },
+  #define RUNTIME_NOTPRODUCT_FLAG_STRUCT(type, name, value, doc) { #type, XSTR(name), &name, doc, "{notproduct}", DEFAULT },
 #endif
 
 #ifdef _LP64
-  #define RUNTIME_LP64_PRODUCT_FLAG_STRUCT(type, name, value, doc) { #type, XSTR(name), &name, "{lp64_product}", DEFAULT },
+  #define RUNTIME_LP64_PRODUCT_FLAG_STRUCT(type, name, value, doc) { #type, XSTR(name), &name, NON_PRODUCT_STRING(doc), "{lp64_product}", DEFAULT },
 #else
   #define RUNTIME_LP64_PRODUCT_FLAG_STRUCT(type, name, value, doc) /* flag is constant */
 #endif // _LP64
 
-#define C1_PRODUCT_FLAG_STRUCT(type, name, value, doc) { #type, XSTR(name), &name, "{C1 product}", DEFAULT },
-#define C1_PD_PRODUCT_FLAG_STRUCT(type, name, doc)     { #type, XSTR(name), &name, "{C1 pd product}", DEFAULT },
+#define C1_PRODUCT_FLAG_STRUCT(type, name, value, doc) { #type, XSTR(name), &name, NON_PRODUCT_STRING(doc), "{C1 product}", DEFAULT },
+#define C1_PD_PRODUCT_FLAG_STRUCT(type, name, doc)     { #type, XSTR(name), &name, NON_PRODUCT_STRING(doc), "{C1 pd product}", DEFAULT },
 #ifdef PRODUCT
   #define C1_DEVELOP_FLAG_STRUCT(type, name, value, doc) /* flag is constant */
   #define C1_PD_DEVELOP_FLAG_STRUCT(type, name, doc)     /* flag is constant */
   #define C1_NOTPRODUCT_FLAG_STRUCT(type, name, value, doc)
 #else
-  #define C1_DEVELOP_FLAG_STRUCT(type, name, value, doc) { #type, XSTR(name), &name, "{C1}", DEFAULT },
-  #define C1_PD_DEVELOP_FLAG_STRUCT(type, name, doc)     { #type, XSTR(name), &name, "{C1 pd}", DEFAULT },
-  #define C1_NOTPRODUCT_FLAG_STRUCT(type, name, value, doc) { #type, XSTR(name), &name, "{C1 notproduct}", DEFAULT },
+  #define C1_DEVELOP_FLAG_STRUCT(type, name, value, doc) { #type, XSTR(name), &name, doc, "{C1}", DEFAULT },
+  #define C1_PD_DEVELOP_FLAG_STRUCT(type, name, doc)     { #type, XSTR(name), &name, doc, "{C1 pd}", DEFAULT },
+  #define C1_NOTPRODUCT_FLAG_STRUCT(type, name, value, doc) { #type, XSTR(name), &name, doc, "{C1 notproduct}", DEFAULT },
 #endif
 
 
-#define C2_PRODUCT_FLAG_STRUCT(type, name, value, doc) { #type, XSTR(name), &name, "{C2 product}", DEFAULT },
-#define C2_PD_PRODUCT_FLAG_STRUCT(type, name, doc)     { #type, XSTR(name), &name, "{C2 pd product}", DEFAULT },
-#define C2_DIAGNOSTIC_FLAG_STRUCT(type, name, value, doc) { #type, XSTR(name), &name, "{C2 diagnostic}", DEFAULT },
-#define C2_EXPERIMENTAL_FLAG_STRUCT(type, name, value, doc) { #type, XSTR(name), &name, "{C2 experimental}", DEFAULT },
+#define C2_PRODUCT_FLAG_STRUCT(type, name, value, doc) { #type, XSTR(name), &name, NON_PRODUCT_STRING(doc), "{C2 product}", DEFAULT },
+#define C2_PD_PRODUCT_FLAG_STRUCT(type, name, doc)     { #type, XSTR(name), &name, NON_PRODUCT_STRING(doc), "{C2 pd product}", DEFAULT },
+#define C2_DIAGNOSTIC_FLAG_STRUCT(type, name, value, doc) { #type, XSTR(name), &name, NON_PRODUCT_STRING(doc), "{C2 diagnostic}", DEFAULT },
+#define C2_EXPERIMENTAL_FLAG_STRUCT(type, name, value, doc) { #type, XSTR(name), &name, NON_PRODUCT_STRING(doc), "{C2 experimental}", DEFAULT },
 #ifdef PRODUCT
   #define C2_DEVELOP_FLAG_STRUCT(type, name, value, doc) /* flag is constant */
   #define C2_PD_DEVELOP_FLAG_STRUCT(type, name, doc)     /* flag is constant */
   #define C2_NOTPRODUCT_FLAG_STRUCT(type, name, value, doc)
 #else
-  #define C2_DEVELOP_FLAG_STRUCT(type, name, value, doc) { #type, XSTR(name), &name, "{C2}", DEFAULT },
-  #define C2_PD_DEVELOP_FLAG_STRUCT(type, name, doc)     { #type, XSTR(name), &name, "{C2 pd}", DEFAULT },
-  #define C2_NOTPRODUCT_FLAG_STRUCT(type, name, value, doc) { #type, XSTR(name), &name, "{C2 notproduct}", DEFAULT },
+  #define C2_DEVELOP_FLAG_STRUCT(type, name, value, doc) { #type, XSTR(name), &name, doc, "{C2}", DEFAULT },
+  #define C2_PD_DEVELOP_FLAG_STRUCT(type, name, doc)     { #type, XSTR(name), &name, doc, "{C2 pd}", DEFAULT },
+  #define C2_NOTPRODUCT_FLAG_STRUCT(type, name, value, doc) { #type, XSTR(name), &name, doc, "{C2 notproduct}", DEFAULT },
 #endif
 
-#define SHARK_PRODUCT_FLAG_STRUCT(type, name, value, doc) { #type, XSTR(name), &name, "{Shark product}", DEFAULT },
-#define SHARK_PD_PRODUCT_FLAG_STRUCT(type, name, doc)     { #type, XSTR(name), &name, "{Shark pd product}", DEFAULT },
-#define SHARK_DIAGNOSTIC_FLAG_STRUCT(type, name, value, doc) { #type, XSTR(name), &name, "{Shark diagnostic}", DEFAULT },
+#define SHARK_PRODUCT_FLAG_STRUCT(type, name, value, doc) { #type, XSTR(name), &name, NON_PRODUCT_STRING(doc), "{Shark product}", DEFAULT },
+#define SHARK_PD_PRODUCT_FLAG_STRUCT(type, name, doc)     { #type, XSTR(name), &name, NON_PRODUCT_STRING(doc), "{Shark pd product}", DEFAULT },
+#define SHARK_DIAGNOSTIC_FLAG_STRUCT(type, name, value, doc) { #type, XSTR(name), &name, NON_PRODUCT_STRING(doc), "{Shark diagnostic}", DEFAULT },
 #ifdef PRODUCT
   #define SHARK_DEVELOP_FLAG_STRUCT(type, name, value, doc) /* flag is constant */
   #define SHARK_PD_DEVELOP_FLAG_STRUCT(type, name, doc)     /* flag is constant */
   #define SHARK_NOTPRODUCT_FLAG_STRUCT(type, name, value, doc)
 #else
-  #define SHARK_DEVELOP_FLAG_STRUCT(type, name, value, doc) { #type, XSTR(name), &name, "{Shark}", DEFAULT },
-  #define SHARK_PD_DEVELOP_FLAG_STRUCT(type, name, doc)     { #type, XSTR(name), &name, "{Shark pd}", DEFAULT },
-  #define SHARK_NOTPRODUCT_FLAG_STRUCT(type, name, value, doc) { #type, XSTR(name), &name, "{Shark notproduct}", DEFAULT },
+  #define SHARK_DEVELOP_FLAG_STRUCT(type, name, value, doc) { #type, XSTR(name), &name, doc, "{Shark}", DEFAULT },
+  #define SHARK_PD_DEVELOP_FLAG_STRUCT(type, name, doc)     { #type, XSTR(name), &name, doc, "{Shark pd}", DEFAULT },
+  #define SHARK_NOTPRODUCT_FLAG_STRUCT(type, name, value, doc) { #type, XSTR(name), &name, doc, "{Shark notproduct}", DEFAULT },
 #endif
 
 static Flag flagTable[] = {
@@ -485,7 +497,7 @@
 
 #endif // PRODUCT
 
-void CommandLineFlags::printFlags() {
+void CommandLineFlags::printFlags(bool withCommets) {
   // Print the flags sorted by name
   // note: this method is called before the thread structure is in place
   //       which means resource allocation cannot be used.
@@ -505,7 +517,7 @@
   tty->print_cr("[Global flags]");
   for (int i = 0; i < length; i++) {
     if (array[i]->is_unlocked()) {
-      array[i]->print_on(tty);
+      array[i]->print_on(tty, withCommets);
     }
   }
   FREE_C_HEAP_ARRAY(Flag*, array);
--- old/src/share/vm/runtime/globals.hpp	Tue Aug 24 10:17:20 2010
+++ new/src/share/vm/runtime/globals.hpp	Tue Aug 24 10:17:18 2010
@@ -90,6 +90,7 @@
   const char *type;
   const char *name;
   void*       addr;
+  const char *doc;
   const char *kind;
   FlagValueOrigin origin;
 
@@ -131,7 +132,7 @@
   bool is_writeable() const;
   bool is_external() const;
 
-  void print_on(outputStream* st);
+  void print_on(outputStream* st, bool withComments);
   void print_as_flag(outputStream* st);
 };
 
@@ -211,7 +212,7 @@
   static bool wasSetOnCmdline(const char* name, bool* value);
   static void printSetFlags();
 
-  static void printFlags();
+  static void printFlags(bool withCommets);
 
   static void verify() PRODUCT_RETURN;
 };
                                     
2010-08-24
EVALUATION

http://hg.openjdk.java.net/jdk7/hotspot-rt/hotspot/rev/6ee479178066
                                     
2010-09-02
EVALUATION

http://hg.openjdk.java.net/jdk7/hotspot/hotspot/rev/6ee479178066
                                     
2010-09-08



Hardware and Software, Engineered to Work Together