7903889: jcstress: document used properites (and env variables)

Known properties unifed in one class and printed in verbose help:
The verbose help can be removed, the individual properties with defaults
can be wrapped to its class. Even the OptionSpec and OptionFormatter can
be used if needed

jcstress-core/src/main/java/org/openjdk/jcstress/Options.java

@@ -46,6 +46,8 @@
  * @author Aleksey Shipilev ([email protected])
  */
 public class Options {
+    public static final String TIME_BUDGET_SWITCH = "tb";
+
     private String resultDir;
     private String testFilter;
     private int strideSize;
@@ -89,11 +91,11 @@ public boolean parse() throws IOException {
                 .withRequiredArg().ofType(String.class).describedAs("regexp");
 
         OptionSpec<Integer> strideSize = parser.accepts("strideSize", "Internal stride size. Larger value decreases " +
-                "the synchronization overhead, but also reduces the number of collisions.")
+                        "the synchronization overhead, but also reduces the number of collisions.")
                 .withRequiredArg().ofType(Integer.class).describedAs("N");
 
         OptionSpec<Integer> strideCount = parser.accepts("strideCount", "Internal stride count per epoch. " +
-                "Larger value increases cache footprint.")
+                        "Larger value increases cache footprint.")
                 .withRequiredArg().ofType(Integer.class).describedAs("N");
 
         OptionSpec<Integer> optTime = parser.accepts("time", "(Deprecated, to be removed in next releases.)")
@@ -103,36 +105,36 @@ public boolean parse() throws IOException {
                 .withRequiredArg().ofType(Integer.class).describedAs("N");
 
         OptionSpec<Integer> cpus = parser.accepts("c", "Number of CPUs to use. Defaults to all CPUs in the system. " +
-                "Reducing the number of CPUs limits the amount of resources (including memory) the run is using.")
+                        "Reducing the number of CPUs limits the amount of resources (including memory) the run is using.")
                 .withRequiredArg().ofType(Integer.class).describedAs("N");
 
         OptionSpec<Integer> heapPerFork = parser.accepts("hs", "Java heap size per fork, in megabytes. This " +
-                "affects the stride size: maximum footprint will never be exceeded, regardless of min/max stride sizes.")
+                        "affects the stride size: maximum footprint will never be exceeded, regardless of min/max stride sizes.")
                 .withRequiredArg().ofType(Integer.class).describedAs("MB");
 
         OptionSpec<SpinLoopStyle> spinStyle = parser.accepts("spinStyle", "Busy loop wait style. " +
-                "HARD = hard busy loop; THREAD_YIELD = use Thread.yield(); THREAD_SPIN_WAIT = use Thread.onSpinWait(); LOCKSUPPORT_PARK_NANOS = use LockSupport.parkNanos().")
+                        "HARD = hard busy loop; THREAD_YIELD = use Thread.yield(); THREAD_SPIN_WAIT = use Thread.onSpinWait(); LOCKSUPPORT_PARK_NANOS = use LockSupport.parkNanos().")
                 .withRequiredArg().ofType(SpinLoopStyle.class).describedAs("style");
 
         OptionSpec<Integer> forks = parser.accepts("f", "Should fork each test N times. \"0\" to run in the embedded mode " +
-                "with occasional forking.")
+                        "with occasional forking.")
                 .withOptionalArg().ofType(Integer.class).describedAs("count");
 
         OptionSpec<Integer> forksStressMultiplier = parser.accepts("fsm", "Fork multiplier for randomized/stress tests. " +
-                "This allows more efficient randomized testing, as each fork would use a different seed.")
+                        "This allows more efficient randomized testing, as each fork would use a different seed.")
                 .withOptionalArg().ofType(Integer.class).describedAs("multiplier");
 
         OptionSpec<String> optModeStr = parser.accepts("m", "(Deprecated, to be removed in next releases).")
                 .withRequiredArg().ofType(String.class).describedAs("mode");
 
         OptionSpec<String> optJvmArgs = parser.accepts("jvmArgs", "Use given JVM arguments. This disables JVM flags auto-detection, " +
-                "and runs only the single JVM mode. Either a single space-separated option line, or multiple options are accepted. " +
-                "This option only affects forked runs.")
+                        "and runs only the single JVM mode. Either a single space-separated option line, or multiple options are accepted. " +
+                        "This option only affects forked runs.")
                 .withRequiredArg().ofType(String.class).describedAs("string");
 
         OptionSpec<String> optJvmArgsPrepend = parser.accepts("jvmArgsPrepend", "Prepend given JVM arguments to auto-detected configurations. " +
-                "Either a single space-separated option line, or multiple options are accepted. " +
-                "This option only affects forked runs.")
+                        "Either a single space-separated option line, or multiple options are accepted. " +
+                        "This option only affects forked runs.")
                 .withRequiredArg().ofType(String.class).describedAs("string");
 
         OptionSpec<Boolean> optSplitCompilation = parser.accepts("sc", "Use split per-actor compilation mode, if available.")
@@ -144,13 +146,13 @@ public boolean parse() throws IOException {
         OptionSpec<Boolean> optPretouchHeap = parser.accepts("pth", "Pre-touch Java heap, if possible.")
                 .withOptionalArg().ofType(Boolean.class).describedAs("bool");
 
-        OptionSpec<TimeValue> optTimeBudget = parser.accepts("tb", "Time budget to run the tests. Harness code would try to fit the entire " +
-                "run in the desired timeframe. This value is expected to be reasonable, as it is not guaranteed that tests would succeed " +
-                "in arbitrarily low time budget. If not set, harness would try to decide a reasonable time, given the number of tests to run. " +
-                "Common time suffixes (s/m/h/d) are accepted.")
+        OptionSpec<TimeValue> optTimeBudget = parser.accepts(TIME_BUDGET_SWITCH, "Time budget to run the tests. Harness code would try to fit the entire " +
+                        "run in the desired timeframe. This value is expected to be reasonable, as it is not guaranteed that tests would succeed " +
+                        "in arbitrarily low time budget. If not set, harness would try to decide a reasonable time, given the number of tests to run. " +
+                        "Common time suffixes (s/m/h/d) are accepted.")
                 .withRequiredArg().ofType(TimeValue.class).describedAs("time");
 
-        parser.accepts("v", "Be verbose.");
+        parser.accepts("v", "Be verbose. Will print known properties in help");
         parser.accepts("vv", "Be extra verbose.");
         parser.accepts("vvv", "Be extra extra verbose.");
         parser.accepts("h", "Print this help.");
@@ -161,12 +163,13 @@ public boolean parse() throws IOException {
         } catch (OptionException e) {
             System.err.println("ERROR: " + e.getMessage());
             System.err.println();
-            parser.printHelpOn(System.err);
+            printHelp(parser, System.err);
             return false;
         }
+        setVerbosity(set);
 
         if (set.has("h")) {
-            parser.printHelpOn(System.out);
+            printHelp(parser, System.out);
             return false;
         }
 
@@ -185,23 +188,14 @@ public boolean parse() throws IOException {
             this.resultFile = "jcstress-results-" + timestamp + ".bin.gz";
         }
         this.list = orDefault(set.has(list), false);
-        if (set.has("vvv")) {
-            this.verbosity = new Verbosity(3);
-        } else if (set.has("vv")) {
-            this.verbosity = new Verbosity(2);
-        } else if (set.has("v")) {
-            this.verbosity = new Verbosity(1);
-        } else {
-            this.verbosity = new Verbosity(0);
-        }
 
         int totalCpuCount = VMSupport.figureOutHotCPUs();
         cpuCount = orDefault(set.valueOf(cpus), totalCpuCount);
 
         if (cpuCount > totalCpuCount) {
             System.err.println("Requested to use " + cpuCount + " CPUs, but system has only " + totalCpuCount + " CPUs.");
             System.err.println();
-            parser.printHelpOn(System.err);
+            printHelp(parser, System.err);
             return false;
         }
 
@@ -227,21 +221,21 @@ public boolean parse() throws IOException {
         if (optModeStr.value(set) != null) {
             System.err.println("-m option is not supported anymore, please use -tb.");
             System.err.println();
-            parser.printHelpOn(System.err);
+            printHelp(parser, System.err);
             return false;
         }
 
         if (optTime.value(set) != null) {
             System.err.println("-time option is not supported anymore, please use -tb.");
             System.err.println();
-            parser.printHelpOn(System.err);
+            printHelp(parser, System.err);
             return false;
         }
 
         if (optIters.value(set) != null) {
             System.err.println("-iters option is not supported anymore, please use -tb.");
             System.err.println();
-            parser.printHelpOn(System.err);
+            printHelp(parser, System.err);
             return false;
         }
 
@@ -263,6 +257,26 @@ public boolean parse() throws IOException {
         return true;
     }
 
+    private void setVerbosity(OptionSet set) {
+        if (set.has("vvv")) {
+            this.verbosity = new Verbosity(3);
+        } else if (set.has("vv")) {
+            this.verbosity = new Verbosity(2);
+        } else if (set.has("v")) {
+            this.verbosity = new Verbosity(1);
+        } else {
+            this.verbosity = new Verbosity(0);
+        }
+    }
+
+    private void printHelp(OptionParser parser, PrintStream ouer) throws IOException {
+        parser.printHelpOn(ouer);
+        ouer.println();
+        if (verbosity != null && verbosity.printAllTests()) {
+            UsedProperties.printHelpOn(ouer);
+        }
+    }
+
     private List<String> processArgs(OptionSpec<String> op, OptionSet set) {
         if (set.hasArgument(op)) {
             try {
@@ -297,7 +311,7 @@ public void printSettingsOn(PrintStream out) {
         out.printf("    Hardware CPUs in use: %d%n", getCPUCount());
         out.printf("    Spinning style: %s%n", getSpinStyle());
         out.printf("    Test selection: \"%s\"%n", getTestFilter());
-        out.printf("    Forks per test: %d normal, %d stress%n", getForks(), getForks()*getForksStressMultiplier());
+        out.printf("    Forks per test: %d normal, %d stress%n", getForks(), getForks() * getForksStressMultiplier());
         out.printf("    Test stride: %d strides x %d tests, but taking no more than %d Mb%n", getStrideCount(), getStrideSize(), getMaxFootprintMb());
         out.printf("    Test result blob: \"%s\"%n", resultFile);
         out.printf("    Test results: \"%s\"%n", resultDir);
@@ -392,6 +406,8 @@ public boolean isPretouchHeap() {
         return pretouchHeap;
     }
 
-    public TimeValue timeBudget() { return timeBudget; }
+    public TimeValue timeBudget() {
+        return timeBudget;
+    }
 
 }

jcstress-core/src/main/java/org/openjdk/jcstress/TimeBudget.java

@@ -34,9 +34,9 @@
 
 public class TimeBudget {
 
-    static final int DEFAULT_PER_TEST_MS = Integer.getInteger("jcstress.timeBudget.defaultPerTestMs", 3000);
-    static final int MIN_TIME_MS = Integer.getInteger("jcstress.timeBudget.minTimeMs", 30);
-    static final int MAX_TIME_MS = Integer.getInteger("jcstress.timeBudget.maxTimeMs", 60_000);
+    static final int DEFAULT_PER_TEST_MS =  UsedProperties.getJcstressTimeBudgetDefaultPerTestMs();
+    static final int MIN_TIME_MS = UsedProperties.getJcstressTimeBudgetMinTimeMs();
+    static final int MAX_TIME_MS = UsedProperties.getJcstressTimeBudgetMaxTimeMs();
 
     final long endTime;
     final int expectedTests;

jcstress-core/src/main/java/org/openjdk/jcstress/UsedProperties.java

@@ -0,0 +1,152 @@
+/*
+ * Copyright (c) 2005, 2014, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.  Oracle designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+package org.openjdk.jcstress;
+
+import java.io.PrintStream;
+import java.net.InetAddress;
+import java.net.UnknownHostException;
+
+/**
+ * Known Properties affecting JCStress. Some of them publicly document themselves, some do not need to.
+ */
+public class UsedProperties {
+    private static final String JCSTRESS_TIMEBUDGET_DEFAULTPERTESTMS = "jcstress.timeBudget.defaultPerTestMs";
+    private static final int JCSTRESS_TIMEBUDGET_DEFAULTPERTESTMS_DEFAULT = 3000;
+    private static final String JCSTRESS_TIMEBUDGET_DEFAULTPERTESTMS_COMMENT = JCSTRESS_TIMEBUDGET_DEFAULTPERTESTMS +
+            " set default time the individual test executes. Defaults to " + JCSTRESS_TIMEBUDGET_DEFAULTPERTESTMS_DEFAULT +
+            "ms set to " + getJcstressTimeBudgetDefaultPerTestMs() + "ms";
+
+    private static final String JCSTRESS_TIMEBUDGET_MINTIMEMS = "jcstress.timeBudget.minTimeMs";
+    private static final int JCSTRESS_TIMEBUDGET_MINTIMEMS_DEFAULT = 30;
+    private static final String JCSTRESS_TIMEBUDGET_MINTIMEMS_COMMENT = JCSTRESS_TIMEBUDGET_MINTIMEMS +
+            " set minimal time the individual test executes. Defaults to " + JCSTRESS_TIMEBUDGET_MINTIMEMS_DEFAULT +
+            "ms set to " + getJcstressTimeBudgetMinTimeMs() + "ms";
+
+    private static final String JCSTRESS_TIMEBUDGET_MAXTIMEMS = "jcstress.timeBudget.maxTimeMs";
+    private static final int JCSTRESS_TIMEBUDGET_MAXTIMEMS_DEFAULT = 60_000;
+    private static final String JCSTRESS_TIMEBUDGET_MAXTIMEMS_COMMENT = JCSTRESS_TIMEBUDGET_MAXTIMEMS +
+            " set maximum time the individual test executes. Defaults to " + JCSTRESS_TIMEBUDGET_MAXTIMEMS_DEFAULT +
+            "ms set to " + getJcstressTimeBudgetMaxTimeMs() + "ms";
+
+    private static final String JCSTRESS_TIMEBUDGET_ADDITIONAL_COMMENT = "The time each test is run is (simplified) calculated as value of " + Options.TIME_BUDGET_SWITCH + " switch divided by number of tests (after all filters applied)" +
+            " If te resulting time is smaller then " + JCSTRESS_TIMEBUDGET_MINTIMEMS + ", it is used.  If it si bigger then " + JCSTRESS_TIMEBUDGET_MAXTIMEMS + " it is used. If no " + Options.TIME_BUDGET_SWITCH + "  is set," +
+            " then " + JCSTRESS_TIMEBUDGET_DEFAULTPERTESTMS + " is used. See " + Options.TIME_BUDGET_SWITCH + " for more info. Properties do not accept unit suffixes.";
+
+    private static final String JCSTRESS_LINK_ADDRESS = "jcstress.link.address";
+    private static final String JCSTRESS_LINK_ADDRESS_COMMENT = JCSTRESS_LINK_ADDRESS + " is address where to connect to forked VMs. Defaults to loop-back. Set to '" + getListenAddressForInfo() + "'";
+
+    private static final String JCSTRESS_LINK_PORT = "jcstress.link.port";
+    private static final int JCSTRESS_LINK_PORT_DEFAULT = 0;
+    private static final String JCSTRESS_LINK_PORT_COMMENT = JCSTRESS_LINK_PORT + " is port where to connect to forked VMs on " + JCSTRESS_LINK_ADDRESS + ". Defaults to " + JCSTRESS_LINK_PORT_DEFAULT + " (random free port)." +
+            " Set to " + getJcstressLinkPort();
+
+    private static final String JCSTRESS_LINK_TIMEOUTMS = "jcstress.link.timeoutMs";
+    private static final int JCSTRESS_LINK_TIMEOUTMS_DEFAULT = 30 * 1000;
+    private static final String JCSTRESS_LINK_TIMEOUTMS_COMMENT = JCSTRESS_LINK_TIMEOUTMS + " set timeout to forked VM communication ms." +
+            " Defaults to " + JCSTRESS_LINK_TIMEOUTMS_DEFAULT + "ms. Set to " + getJcstressLinkTimeoutMs() + "ms.";
+
+    private static final String JCSTRESS_CONSOLE_PRINTINTERVALMS = "jcstress.console.printIntervalMs";
+    private static final long JCSTRESS_CONSOLE_PRINTINTERVALMS_INTERACTIVE_DEFAULT = 1_000;
+    private static final long JCSTRESS_CONSOLE_PRINTINTERVALMS_NONINTERACTIVE_DEFAULT = 15_000;
+    private static final String JCSTRESS_CONSOLE_PRINTINTERVALMS_COMMENT = JCSTRESS_CONSOLE_PRINTINTERVALMS + " sets interval how often to print results to console in ms. Have two defaults: " +
+            JCSTRESS_CONSOLE_PRINTINTERVALMS_INTERACTIVE_DEFAULT + "ms in interactive mode and " +
+            JCSTRESS_CONSOLE_PRINTINTERVALMS_NONINTERACTIVE_DEFAULT + "ms in noninteractive mode. Set to " +
+            getPrintIntervalMs() + "ms";
+
+    public static int getJcstressTimeBudgetDefaultPerTestMs() {
+        return Integer.getInteger(JCSTRESS_TIMEBUDGET_DEFAULTPERTESTMS, JCSTRESS_TIMEBUDGET_DEFAULTPERTESTMS_DEFAULT);
+    }
+
+    public static int getJcstressTimeBudgetMinTimeMs() {
+        return Integer.getInteger(JCSTRESS_TIMEBUDGET_MINTIMEMS, JCSTRESS_TIMEBUDGET_MINTIMEMS_DEFAULT);
+    }
+
+    public static int getJcstressTimeBudgetMaxTimeMs() {
+        return Integer.getInteger(JCSTRESS_TIMEBUDGET_MAXTIMEMS, JCSTRESS_TIMEBUDGET_MAXTIMEMS_DEFAULT);
+    }
+
+    private static String getJcstressLinkAddress() {
+        return System.getProperty(JCSTRESS_LINK_ADDRESS);
+    }
+
+    public static String getListenAddressForInfo() {
+        try {
+            return getListenAddress().toString();
+        } catch (Exception ex) {
+            return ex.getMessage();
+        }
+    }
+
+    public static InetAddress getListenAddress() {
+        // Try to use user-provided override first.
+        if (getJcstressLinkAddress() != null) {
+            try {
+                return InetAddress.getByName(getJcstressLinkAddress());
+            } catch (UnknownHostException e) {
+                // override failed, notify user
+                throw new IllegalStateException("Can not initialize binary link.", e);
+            }
+        }
+
+        return InetAddress.getLoopbackAddress();
+    }
+
+    public static int getJcstressLinkPort() {
+        return Integer.getInteger(JCSTRESS_LINK_PORT, JCSTRESS_LINK_PORT_DEFAULT);
+    }
+
+
+    public static int getJcstressLinkTimeoutMs() {
+        return Integer.getInteger(JCSTRESS_LINK_TIMEOUTMS, JCSTRESS_LINK_TIMEOUTMS_DEFAULT);
+    }
+
+    public static boolean isProgressInteractive() {
+        return System.console() != null;
+    }
+
+    private static String getJcstressConsolePrintIntervalMs() {
+        return System.getProperty(JCSTRESS_CONSOLE_PRINTINTERVALMS);
+    }
+
+    public static long getPrintIntervalMs() {
+        return (getJcstressConsolePrintIntervalMs() != null) ?
+                Long.parseLong(getJcstressConsolePrintIntervalMs()) :
+                isProgressInteractive() ? JCSTRESS_CONSOLE_PRINTINTERVALMS_INTERACTIVE_DEFAULT : JCSTRESS_CONSOLE_PRINTINTERVALMS_NONINTERACTIVE_DEFAULT;
+    }
+
+    public static void printHelpOn(PrintStream ouer) {
+        ouer.println("JCStress recognize several internal properties:");
+        ouer.println("  " + JCSTRESS_TIMEBUDGET_DEFAULTPERTESTMS_COMMENT);
+        ouer.println("  " + JCSTRESS_TIMEBUDGET_MINTIMEMS_COMMENT);
+        ouer.println("  " + JCSTRESS_TIMEBUDGET_MAXTIMEMS_COMMENT);
+        ouer.println("  " + JCSTRESS_TIMEBUDGET_ADDITIONAL_COMMENT);
+        ouer.println("  " + JCSTRESS_LINK_ADDRESS_COMMENT);
+        ouer.println("  " + JCSTRESS_LINK_PORT_COMMENT);
+        ouer.println("  " + JCSTRESS_LINK_TIMEOUTMS_COMMENT);
+        ouer.println("  " + JCSTRESS_CONSOLE_PRINTINTERVALMS_COMMENT);
+
+
+    }
+}