changeset 363:1406e1e592a9

JMH Samples also runnable through Java API and have Main methods. (Runnable from IDE!)
author shade
date Thu, 23 Jan 2014 02:03:41 +0400
parents 8f81e562fbf5
children d664e79b3c0b
files jmh-samples/src/main/java/org/openjdk/jmh/samples/JMHSample_01_HelloWorld.java jmh-samples/src/main/java/org/openjdk/jmh/samples/JMHSample_02_BenchmarkModes.java jmh-samples/src/main/java/org/openjdk/jmh/samples/JMHSample_03_States.java jmh-samples/src/main/java/org/openjdk/jmh/samples/JMHSample_04_DefaultState.java jmh-samples/src/main/java/org/openjdk/jmh/samples/JMHSample_05_StateFixtures.java jmh-samples/src/main/java/org/openjdk/jmh/samples/JMHSample_06_FixtureLevel.java jmh-samples/src/main/java/org/openjdk/jmh/samples/JMHSample_07_FixtureLevelInvocation.java jmh-samples/src/main/java/org/openjdk/jmh/samples/JMHSample_08_DeadCode.java jmh-samples/src/main/java/org/openjdk/jmh/samples/JMHSample_09_Blackholes.java jmh-samples/src/main/java/org/openjdk/jmh/samples/JMHSample_10_ConstantFold.java jmh-samples/src/main/java/org/openjdk/jmh/samples/JMHSample_11_Loops.java jmh-samples/src/main/java/org/openjdk/jmh/samples/JMHSample_12_Forking.java jmh-samples/src/main/java/org/openjdk/jmh/samples/JMHSample_13_RunToRun.java jmh-samples/src/main/java/org/openjdk/jmh/samples/JMHSample_15_Asymmetric.java jmh-samples/src/main/java/org/openjdk/jmh/samples/JMHSample_16_CompilerControl.java jmh-samples/src/main/java/org/openjdk/jmh/samples/JMHSample_17_SyncIterations.java jmh-samples/src/main/java/org/openjdk/jmh/samples/JMHSample_18_Control.java jmh-samples/src/main/java/org/openjdk/jmh/samples/JMHSample_20_Annotations.java jmh-samples/src/main/java/org/openjdk/jmh/samples/JMHSample_21_ConsumeCPU.java jmh-samples/src/main/java/org/openjdk/jmh/samples/JMHSample_22_FalseSharing.java jmh-samples/src/main/java/org/openjdk/jmh/samples/JMHSample_23_AuxCounters.java jmh-samples/src/main/java/org/openjdk/jmh/samples/JMHSample_24_Inheritance.java
diffstat 22 files changed, 518 insertions(+), 112 deletions(-) [+]
line wrap: on
line diff
--- a/jmh-samples/src/main/java/org/openjdk/jmh/samples/JMHSample_01_HelloWorld.java	Thu Jan 23 00:20:04 2014 +0400
+++ b/jmh-samples/src/main/java/org/openjdk/jmh/samples/JMHSample_01_HelloWorld.java	Thu Jan 23 02:03:41 2014 +0400
@@ -25,6 +25,10 @@
 package org.openjdk.jmh.samples;
 
 import org.openjdk.jmh.annotations.GenerateMicroBenchmark;
+import org.openjdk.jmh.runner.Runner;
+import org.openjdk.jmh.runner.RunnerException;
+import org.openjdk.jmh.runner.options.Options;
+import org.openjdk.jmh.runner.options.OptionsBuilder;
 
 public class JMHSample_01_HelloWorld {
 
@@ -59,19 +63,31 @@
     }
 
     /*
-     * HOW TO RUN THIS TEST:
-     *
-     * You can run this test with:
-     *    $ mvn clean install
-     *    $ java -jar target/microbenchmarks.jar ".*JMHSample_01.*"
+     * ============================== HOW TO RUN THIS TEST: ====================================
      *
      * You are expected to see the run with large number of iterations, and
      * very large throughput numbers. You can see that as the estimate of the
      * harness overheads per method call. In most of our measurements, it is
      * down to several cycles per call.
      *
+     * a) Via command-line:
+     *    $ mvn clean install
+     *    $ java -jar target/microbenchmarks.jar ".*JMHSample_01.*"
+     *
      * JMH generates self-contained JARs, bundling JMH together with it.
      * The runtime options for the JMH are available with "-h":
      *    $ java -jar target/microbenchmarks.jar -h
+     *
+     * b) Via Java API:
      */
+
+    public static void main(String[] args) throws RunnerException {
+        Options opt = new OptionsBuilder()
+                .include(".*" + JMHSample_01_HelloWorld.class.getSimpleName() + ".*")
+                .forks(1)
+                .build();
+
+        new Runner(opt).run();
+    }
+
 }
--- a/jmh-samples/src/main/java/org/openjdk/jmh/samples/JMHSample_02_BenchmarkModes.java	Thu Jan 23 00:20:04 2014 +0400
+++ b/jmh-samples/src/main/java/org/openjdk/jmh/samples/JMHSample_02_BenchmarkModes.java	Thu Jan 23 02:03:41 2014 +0400
@@ -28,6 +28,10 @@
 import org.openjdk.jmh.annotations.GenerateMicroBenchmark;
 import org.openjdk.jmh.annotations.Mode;
 import org.openjdk.jmh.annotations.OutputTimeUnit;
+import org.openjdk.jmh.runner.Runner;
+import org.openjdk.jmh.runner.RunnerException;
+import org.openjdk.jmh.runner.options.Options;
+import org.openjdk.jmh.runner.options.OptionsBuilder;
 
 import java.util.concurrent.TimeUnit;
 
@@ -130,15 +134,30 @@
     }
 
     /*
-     * HOW TO RUN THIS TEST:
-     *
-     * You can run this test with:
-     *    $ mvn clean install
-     *    $ java -jar target/microbenchmarks.jar ".*JMHSample_02.*" -i 5 -f 1
-     *    (we requested 5 iterations, single fork)
+     * ============================== HOW TO RUN THIS TEST: ====================================
      *
      * You are expected to see the different run modes for the same benchmark.
      * Note the units are different, scores are consistent with each other.
+     *
+     * You can run this test:
+     *
+     * a) Via the command line:
+     *    $ mvn clean install
+     *    $ java -jar target/microbenchmarks.jar ".*JMHSample_02.*" -wi 5 -i 5 -f 1
+     *    (we requested 5 warmup/measurement iterations, single fork)
+     *
+     * b) Via the Java API:
      */
 
+    public static void main(String[] args) throws RunnerException {
+        Options opt = new OptionsBuilder()
+                .include(".*" + JMHSample_02_BenchmarkModes.class.getSimpleName() + ".*")
+                .warmupIterations(5)
+                .measurementIterations(5)
+                .forks(1)
+                .build();
+
+        new Runner(opt).run();
+    }
+
 }
--- a/jmh-samples/src/main/java/org/openjdk/jmh/samples/JMHSample_03_States.java	Thu Jan 23 00:20:04 2014 +0400
+++ b/jmh-samples/src/main/java/org/openjdk/jmh/samples/JMHSample_03_States.java	Thu Jan 23 02:03:41 2014 +0400
@@ -27,6 +27,10 @@
 import org.openjdk.jmh.annotations.GenerateMicroBenchmark;
 import org.openjdk.jmh.annotations.Scope;
 import org.openjdk.jmh.annotations.State;
+import org.openjdk.jmh.runner.Runner;
+import org.openjdk.jmh.runner.RunnerException;
+import org.openjdk.jmh.runner.options.Options;
+import org.openjdk.jmh.runner.options.OptionsBuilder;
 
 public class JMHSample_03_States {
 
@@ -86,16 +90,32 @@
     }
 
     /*
-     * HOW TO RUN THIS TEST:
-     *
-     * You can run this test with:
-     *    $ mvn clean install
-     *    $ java -jar target/microbenchmarks.jar ".*JMHSample_03.*" -i 5 -t 4 -f 1
-     *    (we requested 5 iterations, with 4 threads, single fork)
+     * ============================== HOW TO RUN THIS TEST: ====================================
      *
      * You are expected to see the drastic difference in shared and unshared cases,
      * because you either contend for single memory location, or not. This effect
      * is more articulated on large machines.
+     *
+     * You can run this test:
+     *
+     * a) Via the command line:
+     *    $ mvn clean install
+     *    $ java -jar target/microbenchmarks.jar ".*JMHSample_03.*" -wi 5 -i 5 -t 4 -f 1
+     *    (we requested 5 measurement/warmup iterations, with 4 threads, single fork)
+     *
+     * b) Via the Java API:
      */
 
+    public static void main(String[] args) throws RunnerException {
+        Options opt = new OptionsBuilder()
+                .include(".*" + JMHSample_03_States.class.getSimpleName() + ".*")
+                .warmupIterations(5)
+                .measurementIterations(5)
+                .threads(4)
+                .forks(1)
+                .build();
+
+        new Runner(opt).run();
+    }
+
 }
--- a/jmh-samples/src/main/java/org/openjdk/jmh/samples/JMHSample_04_DefaultState.java	Thu Jan 23 00:20:04 2014 +0400
+++ b/jmh-samples/src/main/java/org/openjdk/jmh/samples/JMHSample_04_DefaultState.java	Thu Jan 23 02:03:41 2014 +0400
@@ -27,6 +27,10 @@
 import org.openjdk.jmh.annotations.GenerateMicroBenchmark;
 import org.openjdk.jmh.annotations.Scope;
 import org.openjdk.jmh.annotations.State;
+import org.openjdk.jmh.runner.Runner;
+import org.openjdk.jmh.runner.RunnerException;
+import org.openjdk.jmh.runner.options.Options;
+import org.openjdk.jmh.runner.options.OptionsBuilder;
 
 /*
  * Fortunately, in many cases you just need a single state object.
@@ -46,14 +50,29 @@
     }
 
     /*
-     * HOW TO RUN THIS TEST:
-     *
-     * You can run this test with:
-     *    $ mvn clean install
-     *    $ java -jar target/microbenchmarks.jar ".*JMHSample_04.*" -i 5 -f 1
-     *    (we requested 5 iterations, single fork)
+     * ============================== HOW TO RUN THIS TEST: ====================================
      *
      * You can see the benchmark runs as usual.
+     *
+     * You can run this test:
+     *
+     * a) Via the command line:
+     *    $ mvn clean install
+     *    $ java -jar target/microbenchmarks.jar ".*JMHSample_04.*" -wi 5 -i 5 -f 1
+     *    (we requested 5 warmup/measurement iterations, single fork)
+     *
+     * b) Via the Java API:
      */
 
+    public static void main(String[] args) throws RunnerException {
+        Options opt = new OptionsBuilder()
+                .include(".*" + JMHSample_04_DefaultState.class.getSimpleName() + ".*")
+                .warmupIterations(5)
+                .measurementIterations(5)
+                .forks(1)
+                .build();
+
+        new Runner(opt).run();
+    }
+
 }
--- a/jmh-samples/src/main/java/org/openjdk/jmh/samples/JMHSample_05_StateFixtures.java	Thu Jan 23 00:20:04 2014 +0400
+++ b/jmh-samples/src/main/java/org/openjdk/jmh/samples/JMHSample_05_StateFixtures.java	Thu Jan 23 02:03:41 2014 +0400
@@ -29,6 +29,10 @@
 import org.openjdk.jmh.annotations.Setup;
 import org.openjdk.jmh.annotations.State;
 import org.openjdk.jmh.annotations.TearDown;
+import org.openjdk.jmh.runner.Runner;
+import org.openjdk.jmh.runner.RunnerException;
+import org.openjdk.jmh.runner.options.Options;
+import org.openjdk.jmh.runner.options.OptionsBuilder;
 
 @State(Scope.Thread)
 public class JMHSample_05_StateFixtures {
@@ -95,15 +99,31 @@
     }
 
     /*
-     * HOW TO RUN THIS TEST:
-     *
-     * You can run this test with:
-     *    $ mvn clean install
-     *    $ java -ea -jar target/microbenchmarks.jar ".*JMHSample_05.*" -i 5 -f 1
-     *    (we requested 5 iterations, single fork)
+     * ============================== HOW TO RUN THIS TEST: ====================================
      *
      * You can see measureRight() yields the result, and measureWrong() fires
      * the assert at the end of the run.
+     *
+     * You can run this test:
+     *
+     * a) Via the command line:
+     *    $ mvn clean install
+     *    $ java -ea -jar target/microbenchmarks.jar ".*JMHSample_05.*" -wi 5 -i 5 -f 1
+     *    (we requested 5 warmup/measurement iterations, single fork)
+     *
+     * b) Via the Java API:
      */
 
+    public static void main(String[] args) throws RunnerException {
+        Options opt = new OptionsBuilder()
+                .include(".*" + JMHSample_05_StateFixtures.class.getSimpleName() + ".*")
+                .warmupIterations(5)
+                .measurementIterations(5)
+                .forks(1)
+                .jvmArgs("-ea")
+                .build();
+
+        new Runner(opt).run();
+    }
+
 }
--- a/jmh-samples/src/main/java/org/openjdk/jmh/samples/JMHSample_06_FixtureLevel.java	Thu Jan 23 00:20:04 2014 +0400
+++ b/jmh-samples/src/main/java/org/openjdk/jmh/samples/JMHSample_06_FixtureLevel.java	Thu Jan 23 02:03:41 2014 +0400
@@ -29,6 +29,10 @@
 import org.openjdk.jmh.annotations.Scope;
 import org.openjdk.jmh.annotations.State;
 import org.openjdk.jmh.annotations.TearDown;
+import org.openjdk.jmh.runner.Runner;
+import org.openjdk.jmh.runner.RunnerException;
+import org.openjdk.jmh.runner.options.Options;
+import org.openjdk.jmh.runner.options.OptionsBuilder;
 
 @State(Scope.Thread)
 public class JMHSample_06_FixtureLevel {
@@ -65,15 +69,31 @@
     }
 
     /*
-     * HOW TO RUN THIS TEST:
-     *
-     * You can run this test with:
-     *    $ mvn clean install
-     *    $ java -ea -jar target/microbenchmarks.jar ".*JMHSample_06.*" -i 5 -f 1
-     *    (we requested 5 iterations, single fork)
+     * ============================== HOW TO RUN THIS TEST: ====================================
      *
      * You can see measureRight() yields the result, and measureWrong() fires
      * the assert at the end of first iteration!
+     *
+     * You can run this test:
+     *
+     * a) Via the command line:
+     *    $ mvn clean install
+     *    $ java -ea -jar target/microbenchmarks.jar ".*JMHSample_06.*" -wi 5 -i 5 -f 1
+     *    (we requested 5 warmup/measurement iterations, single fork)
+     *
+     * b) Via the Java API:
      */
 
+    public static void main(String[] args) throws RunnerException {
+        Options opt = new OptionsBuilder()
+                .include(".*" + JMHSample_06_FixtureLevel.class.getSimpleName() + ".*")
+                .warmupIterations(5)
+                .measurementIterations(5)
+                .forks(1)
+                .jvmArgs("-ea")
+                .build();
+
+        new Runner(opt).run();
+    }
+
 }
--- a/jmh-samples/src/main/java/org/openjdk/jmh/samples/JMHSample_07_FixtureLevelInvocation.java	Thu Jan 23 00:20:04 2014 +0400
+++ b/jmh-samples/src/main/java/org/openjdk/jmh/samples/JMHSample_07_FixtureLevelInvocation.java	Thu Jan 23 02:03:41 2014 +0400
@@ -33,6 +33,10 @@
 import org.openjdk.jmh.annotations.Setup;
 import org.openjdk.jmh.annotations.State;
 import org.openjdk.jmh.annotations.TearDown;
+import org.openjdk.jmh.runner.Runner;
+import org.openjdk.jmh.runner.RunnerException;
+import org.openjdk.jmh.runner.options.Options;
+import org.openjdk.jmh.runner.options.OptionsBuilder;
 
 import java.util.concurrent.Callable;
 import java.util.concurrent.ExecutionException;
@@ -144,15 +148,28 @@
     }
 
     /*
-     * HOW TO RUN THIS TEST:
-     *
-     * You can run this test with:
-     *    $ mvn clean install
-     *    $ java -jar target/microbenchmarks.jar ".*JMHSample_07.*" -i 5 -f 1
-     *    (we requested 5 iterations, single fork)
+     * ============================== HOW TO RUN THIS TEST: ====================================
      *
      * You can see the cold scenario is running longer, because we pay for
      * thread wakeups.
+     *
+     * You can run this test:
+     *
+     * a) Via the command line:
+     *    $ mvn clean install
+     *    $ java -jar target/microbenchmarks.jar ".*JMHSample_07.*" -wi 5 -i 5 -f 1
+     *    (we requested 5 warmup/measurement iterations, single fork)
      */
 
+    public static void main(String[] args) throws RunnerException {
+        Options opt = new OptionsBuilder()
+                .include(".*" + JMHSample_07_FixtureLevelInvocation.class.getSimpleName() + ".*")
+                .warmupIterations(5)
+                .measurementIterations(5)
+                .forks(1)
+                .build();
+
+        new Runner(opt).run();
+    }
+
 }
--- a/jmh-samples/src/main/java/org/openjdk/jmh/samples/JMHSample_08_DeadCode.java	Thu Jan 23 00:20:04 2014 +0400
+++ b/jmh-samples/src/main/java/org/openjdk/jmh/samples/JMHSample_08_DeadCode.java	Thu Jan 23 02:03:41 2014 +0400
@@ -30,6 +30,10 @@
 import org.openjdk.jmh.annotations.OutputTimeUnit;
 import org.openjdk.jmh.annotations.Scope;
 import org.openjdk.jmh.annotations.State;
+import org.openjdk.jmh.runner.Runner;
+import org.openjdk.jmh.runner.RunnerException;
+import org.openjdk.jmh.runner.options.Options;
+import org.openjdk.jmh.runner.options.OptionsBuilder;
 
 import java.util.concurrent.TimeUnit;
 
@@ -68,15 +72,30 @@
     }
 
     /*
-     * HOW TO RUN THIS TEST:
-     *
-     * You can run this test with:
-     *    $ mvn clean install
-     *    $ java -jar target/microbenchmarks.jar ".*JMHSample_08.*" -i 5 -f 1
-     *    (we requested 5 iterations, single fork)
+     * ============================== HOW TO RUN THIS TEST: ====================================
      *
      * You can see the unrealistically fast calculation in with measureWrong(),
      * while realistic measurement with measureRight().
+     *
+     * You can run this test:
+     *
+     * a) Via the command line:
+     *    $ mvn clean install
+     *    $ java -jar target/microbenchmarks.jar ".*JMHSample_08.*" -wi 5 -i 5 -f 1
+     *    (we requested 5 warmup/measurement iterations, single fork)
+     *
+     * b) Via the Java API:
      */
 
+    public static void main(String[] args) throws RunnerException {
+        Options opt = new OptionsBuilder()
+                .include(".*" + JMHSample_08_DeadCode.class.getSimpleName() + ".*")
+                .warmupIterations(5)
+                .measurementIterations(5)
+                .forks(1)
+                .build();
+
+        new Runner(opt).run();
+    }
+
 }
--- a/jmh-samples/src/main/java/org/openjdk/jmh/samples/JMHSample_09_Blackholes.java	Thu Jan 23 00:20:04 2014 +0400
+++ b/jmh-samples/src/main/java/org/openjdk/jmh/samples/JMHSample_09_Blackholes.java	Thu Jan 23 02:03:41 2014 +0400
@@ -31,6 +31,10 @@
 import org.openjdk.jmh.annotations.Scope;
 import org.openjdk.jmh.annotations.State;
 import org.openjdk.jmh.logic.BlackHole;
+import org.openjdk.jmh.runner.Runner;
+import org.openjdk.jmh.runner.RunnerException;
+import org.openjdk.jmh.runner.options.Options;
+import org.openjdk.jmh.runner.options.OptionsBuilder;
 
 import java.util.concurrent.TimeUnit;
 
@@ -93,15 +97,31 @@
     }
 
     /*
-     * HOW TO RUN THIS TEST:
-     *
-     * You can run this test with:
-     *    $ mvn clean install
-     *    $ java -jar target/microbenchmarks.jar ".*JMHSample_09.*" -i 5 -f 1
-     *    (we requested 5 iterations, single fork)
+     * ============================== HOW TO RUN THIS TEST: ====================================
      *
      * You will see measureWrong() running on-par with baseline().
      * Both measureRight() are measuring twice the baseline, so the logs are intact.
+     *
+     * You can run this test:
+     *
+     * a) Via the command line:
+     *    $ mvn clean install
+     *    $ java -jar target/microbenchmarks.jar ".*JMHSample_09.*" -wi 5 -i 5 -f 1
+     *    (we requested 5 warmup/measurement iterations, single fork)
+     *
+     * b) Via the Java API:
      */
 
+    public static void main(String[] args) throws RunnerException {
+        Options opt = new OptionsBuilder()
+                .include(".*" + JMHSample_09_Blackholes.class.getSimpleName() + ".*")
+                .warmupIterations(5)
+                .measurementIterations(5)
+                .forks(1)
+                .build();
+
+        new Runner(opt).run();
+    }
+
+
 }
--- a/jmh-samples/src/main/java/org/openjdk/jmh/samples/JMHSample_10_ConstantFold.java	Thu Jan 23 00:20:04 2014 +0400
+++ b/jmh-samples/src/main/java/org/openjdk/jmh/samples/JMHSample_10_ConstantFold.java	Thu Jan 23 02:03:41 2014 +0400
@@ -30,6 +30,10 @@
 import org.openjdk.jmh.annotations.OutputTimeUnit;
 import org.openjdk.jmh.annotations.Scope;
 import org.openjdk.jmh.annotations.State;
+import org.openjdk.jmh.runner.Runner;
+import org.openjdk.jmh.runner.RunnerException;
+import org.openjdk.jmh.runner.options.Options;
+import org.openjdk.jmh.runner.options.OptionsBuilder;
 
 import java.util.concurrent.TimeUnit;
 
@@ -70,15 +74,30 @@
     }
 
     /*
-     * HOW TO RUN THIS TEST:
+     * ============================== HOW TO RUN THIS TEST: ====================================
      *
-     * You can run this test with:
+     * You can see the unrealistically fast calculation in with measureWrong(),
+     * while realistic measurement with measureRight().
+     *
+     * You can run this test:
+     *
+     * a) Via the command line:
      *    $ mvn clean install
      *    $ java -jar target/microbenchmarks.jar ".*JMHSample_10.*" -i 5 -f 1
      *    (we requested 5 iterations, single fork)
      *
-     * You can see the unrealistically fast calculation in with measureWrong(),
-     * while realistic measurement with measureRight().
+     * b) Via the Java API:
      */
 
+    public static void main(String[] args) throws RunnerException {
+        Options opt = new OptionsBuilder()
+                .include(".*" + JMHSample_10_ConstantFold.class.getSimpleName() + ".*")
+                .warmupIterations(5)
+                .measurementIterations(5)
+                .forks(1)
+                .build();
+
+        new Runner(opt).run();
+    }
+
 }
--- a/jmh-samples/src/main/java/org/openjdk/jmh/samples/JMHSample_11_Loops.java	Thu Jan 23 00:20:04 2014 +0400
+++ b/jmh-samples/src/main/java/org/openjdk/jmh/samples/JMHSample_11_Loops.java	Thu Jan 23 02:03:41 2014 +0400
@@ -31,6 +31,10 @@
 import org.openjdk.jmh.annotations.OutputTimeUnit;
 import org.openjdk.jmh.annotations.Scope;
 import org.openjdk.jmh.annotations.State;
+import org.openjdk.jmh.runner.Runner;
+import org.openjdk.jmh.runner.RunnerException;
+import org.openjdk.jmh.runner.options.Options;
+import org.openjdk.jmh.runner.options.OptionsBuilder;
 
 import java.util.concurrent.TimeUnit;
 
@@ -120,12 +124,7 @@
     }
 
     /*
-     * HOW TO RUN THIS TEST:
-     *
-     * You can run this test with:
-     *    $ mvn clean install
-     *    $ java -jar target/microbenchmarks.jar ".*JMHSample_11.*" -i 5 -f 1
-     *    (we requested 5 iterations, single fork)
+     * ============================== HOW TO RUN THIS TEST: ====================================
      *
      * You might notice the larger the repetitions count, the lower the "perceived"
      * cost of the operation being measured. Up to the point we do each addition with 1/20 ns,
@@ -134,6 +133,26 @@
      * This happens because the loop is heavily unrolled/pipelined, and the operation
      * to be measured is hoisted from the loop. Morale: don't overuse loops, rely on JMH
      * to get the measurement right.
+     *
+     * You can run this test:
+     *
+     * a) Via the command line:
+     *    $ mvn clean install
+     *    $ java -jar target/microbenchmarks.jar ".*JMHSample_11.*" -wi 5 -i 5 -f 1
+     *    (we requested 5 warmup/measurement iterations, single fork)
+     *
+     * b) Via the Java API:
      */
 
+    public static void main(String[] args) throws RunnerException {
+        Options opt = new OptionsBuilder()
+                .include(".*" + JMHSample_11_Loops.class.getSimpleName() + ".*")
+                .warmupIterations(5)
+                .measurementIterations(5)
+                .forks(1)
+                .build();
+
+        new Runner(opt).run();
+    }
+
 }
--- a/jmh-samples/src/main/java/org/openjdk/jmh/samples/JMHSample_12_Forking.java	Thu Jan 23 00:20:04 2014 +0400
+++ b/jmh-samples/src/main/java/org/openjdk/jmh/samples/JMHSample_12_Forking.java	Thu Jan 23 02:03:41 2014 +0400
@@ -31,6 +31,10 @@
 import org.openjdk.jmh.annotations.OutputTimeUnit;
 import org.openjdk.jmh.annotations.Scope;
 import org.openjdk.jmh.annotations.State;
+import org.openjdk.jmh.runner.Runner;
+import org.openjdk.jmh.runner.RunnerException;
+import org.openjdk.jmh.runner.options.Options;
+import org.openjdk.jmh.runner.options.OptionsBuilder;
 
 import java.util.concurrent.TimeUnit;
 
@@ -152,16 +156,30 @@
     }
 
     /*
-     * HOW TO RUN THIS TEST:
-     *
-     * You can run this test with:
-     *    $ mvn clean install
-     *    $ java -jar target/microbenchmarks.jar ".*JMHSample_12.*" -i 5
-     *    (we requested 5 iterations)
+     * ============================== HOW TO RUN THIS TEST: ====================================
      *
      * Note that C1 is faster, C2 is slower, but the C1 is slow again! This is because
      * the profiles for C1 and C2 had merged together. Notice how flawless the measurement
      * is for forked runs.
+     *
+     * You can run this test:
+     *
+     * a) Via the command line:
+     *    $ mvn clean install
+     *    $ java -jar target/microbenchmarks.jar ".*JMHSample_12.*" -wi 5 -i 5
+     *    (we requested 5 warmup/measurement iterations)
+     *
+     * b) Via the Java API:
      */
 
+    public static void main(String[] args) throws RunnerException {
+        Options opt = new OptionsBuilder()
+                .include(".*" + JMHSample_12_Forking.class.getSimpleName() + ".*")
+                .warmupIterations(5)
+                .measurementIterations(5)
+                .build();
+
+        new Runner(opt).run();
+    }
+
 }
--- a/jmh-samples/src/main/java/org/openjdk/jmh/samples/JMHSample_13_RunToRun.java	Thu Jan 23 00:20:04 2014 +0400
+++ b/jmh-samples/src/main/java/org/openjdk/jmh/samples/JMHSample_13_RunToRun.java	Thu Jan 23 02:03:41 2014 +0400
@@ -32,6 +32,10 @@
 import org.openjdk.jmh.annotations.Scope;
 import org.openjdk.jmh.annotations.Setup;
 import org.openjdk.jmh.annotations.State;
+import org.openjdk.jmh.runner.Runner;
+import org.openjdk.jmh.runner.RunnerException;
+import org.openjdk.jmh.runner.options.Options;
+import org.openjdk.jmh.runner.options.OptionsBuilder;
 
 import java.util.concurrent.TimeUnit;
 
@@ -89,15 +93,29 @@
     }
 
     /*
-     * HOW TO RUN THIS TEST:
+     * ============================== HOW TO RUN THIS TEST: ====================================
      *
-     * You can run this test with:
+     * Note the baseline is random within [0..1000] msec; and both forked runs
+     * are estimating the average 500 msec with some confidence.
+     *
+     * You can run this test:
+     *
+     * a) Via the command line:
      *    $ mvn clean install
      *    $ java -jar target/microbenchmarks.jar ".*JMHSample_13.*" -wi 0 -i 3
      *    (we requested no warmup, 3 measurement iterations)
      *
-     * Note the baseline is random within [0..1000] msec; and both forked runs
-     * are estimating the average 500 msec with some confidence.
+     * b) Via the Java API:
      */
 
+    public static void main(String[] args) throws RunnerException {
+        Options opt = new OptionsBuilder()
+                .include(".*" + JMHSample_13_RunToRun.class.getSimpleName() + ".*")
+                .warmupIterations(0)
+                .measurementIterations(5)
+                .build();
+
+        new Runner(opt).run();
+    }
+
 }
--- a/jmh-samples/src/main/java/org/openjdk/jmh/samples/JMHSample_15_Asymmetric.java	Thu Jan 23 00:20:04 2014 +0400
+++ b/jmh-samples/src/main/java/org/openjdk/jmh/samples/JMHSample_15_Asymmetric.java	Thu Jan 23 02:03:41 2014 +0400
@@ -33,6 +33,10 @@
 import org.openjdk.jmh.annotations.Scope;
 import org.openjdk.jmh.annotations.Setup;
 import org.openjdk.jmh.annotations.State;
+import org.openjdk.jmh.runner.Runner;
+import org.openjdk.jmh.runner.RunnerException;
+import org.openjdk.jmh.runner.options.Options;
+import org.openjdk.jmh.runner.options.OptionsBuilder;
 
 import java.util.concurrent.TimeUnit;
 import java.util.concurrent.atomic.AtomicInteger;
@@ -88,14 +92,29 @@
     }
 
     /*
-     * HOW TO RUN THIS TEST:
-     *
-     * You can run this test with:
-     *    $ mvn clean install
-     *    $ java -jar target/microbenchmarks.jar ".*JMHSample_15.*" -i 5 -f 1
-     *    (we requested 5 iterations, single fork)
+     * ============================== HOW TO RUN THIS TEST: ====================================
      *
      * You will have the distinct metrics for inc() and get() from this run.
+     *
+     * You can run this test:
+     *
+     * a) Via the command line:
+     *    $ mvn clean install
+     *    $ java -jar target/microbenchmarks.jar ".*JMHSample_15.*" -wi 5 -i 5 -f 1
+     *    (we requested 5 warmup/measurement iterations, single fork)
+     *
+     * b) Via the Java API:
      */
 
+    public static void main(String[] args) throws RunnerException {
+        Options opt = new OptionsBuilder()
+                .include(".*" + JMHSample_15_Asymmetric.class.getSimpleName() + ".*")
+                .warmupIterations(5)
+                .measurementIterations(5)
+                .forks(1)
+                .build();
+
+        new Runner(opt).run();
+    }
+
 }
--- a/jmh-samples/src/main/java/org/openjdk/jmh/samples/JMHSample_16_CompilerControl.java	Thu Jan 23 00:20:04 2014 +0400
+++ b/jmh-samples/src/main/java/org/openjdk/jmh/samples/JMHSample_16_CompilerControl.java	Thu Jan 23 02:03:41 2014 +0400
@@ -31,6 +31,10 @@
 import org.openjdk.jmh.annotations.OutputTimeUnit;
 import org.openjdk.jmh.annotations.Scope;
 import org.openjdk.jmh.annotations.State;
+import org.openjdk.jmh.runner.Runner;
+import org.openjdk.jmh.runner.RunnerException;
+import org.openjdk.jmh.runner.options.Options;
+import org.openjdk.jmh.runner.options.OptionsBuilder;
 
 import java.util.concurrent.TimeUnit;
 
@@ -104,16 +108,31 @@
     }
 
     /*
-     * HOW TO RUN THIS TEST:
+     * ============================== HOW TO RUN THIS TEST: ====================================
      *
-     * You can run this test with:
+     * Note the performance of the baseline, blank, and inline methods are the same.
+     * dontinline differs a bit, because we are making the proper call.
+     * exclude is severely slower, becase we are not compiling it at all.
+     *
+     * You can run this test:
+     *
+     * a) Via the command line:
      *    $ mvn clean install
      *    $ java -jar target/microbenchmarks.jar ".*JMHSample_16.*" -wi 1 -i 3 -f 1
      *    (we requested 1 warmup iterations, 3 iterations, single fork)
      *
-     * Note the performance of the baseline, blank, and inline methods are the same.
-     * dontinline differs a bit, because we are making the proper call.
-     * exclude is severely slower, becase we are not compiling it at all.
+     * b) Via the Java API:
      */
 
+    public static void main(String[] args) throws RunnerException {
+        Options opt = new OptionsBuilder()
+                .include(".*" + JMHSample_16_CompilerControl.class.getSimpleName() + ".*")
+                .warmupIterations(1)
+                .measurementIterations(3)
+                .forks(1)
+                .build();
+
+        new Runner(opt).run();
+    }
+
 }
--- a/jmh-samples/src/main/java/org/openjdk/jmh/samples/JMHSample_17_SyncIterations.java	Thu Jan 23 00:20:04 2014 +0400
+++ b/jmh-samples/src/main/java/org/openjdk/jmh/samples/JMHSample_17_SyncIterations.java	Thu Jan 23 02:03:41 2014 +0400
@@ -28,6 +28,10 @@
 import org.openjdk.jmh.annotations.OutputTimeUnit;
 import org.openjdk.jmh.annotations.Scope;
 import org.openjdk.jmh.annotations.State;
+import org.openjdk.jmh.runner.Runner;
+import org.openjdk.jmh.runner.RunnerException;
+import org.openjdk.jmh.runner.options.Options;
+import org.openjdk.jmh.runner.options.OptionsBuilder;
 
 import java.util.concurrent.TimeUnit;
 
@@ -73,27 +77,44 @@
      */
 
     /*
-     * HOW TO RUN THIS TEST:
+     * ============================== HOW TO RUN THIS TEST: ====================================
      *
      * You will need to oversubscribe the system to make this effect
      * clearly visible; however, this effect can also be shown on the
      * unsaturated systems.*
      *
-     * Say, $CPU is the number of CPUs on your machine.
-     *
-     * You can run this test with:
-     *    $ mvn clean install
-     *    $ java -jar target/microbenchmarks.jar ".*JMHSample_17.*" \
-     *        -i 20 -wi 1 -f 1 -t ${CPU*16} -si {true|false}
-     *    (we requested 1 warmup iterations, 20 iterations, single fork,
-     *     lots of threads, and changeable "synchronize iterations" option)
-     *
      * Note the performance of -si false version is more flaky, even
      * though it is "better". This is the false improvement, granted by
      * some of the threads executing in solo. The -si true version more stable
      * and coherent.
      *
      * -si true is enabled by default.
+     *
+     * Say, $CPU is the number of CPUs on your machine.
+     *
+     * You can run this test with:
+     *
+     * a) Via the command line:
+     *    $ mvn clean install
+     *    $ java -jar target/microbenchmarks.jar ".*JMHSample_17.*" \
+     *        -i 20 -wi 1 -f 1 -t ${CPU*16} -si {true|false}
+     *    (we requested 1 warmup iterations, 20 iterations, single fork,
+     *     lots of threads, and changeable "synchronize iterations" option)
+     *
+     * b) Via the Java API:
      */
 
+    public static void main(String[] args) throws RunnerException {
+        Options opt = new OptionsBuilder()
+                .include(".*" + JMHSample_17_SyncIterations.class.getSimpleName() + ".*")
+                .warmupIterations(1)
+                .measurementIterations(20)
+                .threads(Runtime.getRuntime().availableProcessors()*16)
+                .forks(1)
+                .syncIterations(true) // try to switch to "false"
+                .build();
+
+        new Runner(opt).run();
+    }
+
 }
--- a/jmh-samples/src/main/java/org/openjdk/jmh/samples/JMHSample_18_Control.java	Thu Jan 23 00:20:04 2014 +0400
+++ b/jmh-samples/src/main/java/org/openjdk/jmh/samples/JMHSample_18_Control.java	Thu Jan 23 02:03:41 2014 +0400
@@ -29,6 +29,10 @@
 import org.openjdk.jmh.annotations.Scope;
 import org.openjdk.jmh.annotations.State;
 import org.openjdk.jmh.logic.Control;
+import org.openjdk.jmh.runner.Runner;
+import org.openjdk.jmh.runner.RunnerException;
+import org.openjdk.jmh.runner.options.Options;
+import org.openjdk.jmh.runner.options.OptionsBuilder;
 
 import java.util.concurrent.atomic.AtomicBoolean;
 
@@ -68,12 +72,28 @@
     }
 
     /*
-     * HOW TO RUN THIS TEST:
+     * ============================== HOW TO RUN THIS TEST: ====================================
      *
-     * You can run this test with:
+     * You can run this test:
+     *
+     * a) Via the command line:
      *    $ mvn clean install
      *    $ java -jar target/microbenchmarks.jar ".*JMHSample_18.*" -wi 1 -i 5 -t 2 -f 1
      *    (we requested 1 warmup iterations, 5 iterations, 2 threads, and single fork)
+     *
+     * b) Via the Java API:
      */
 
+    public static void main(String[] args) throws RunnerException {
+        Options opt = new OptionsBuilder()
+                .include(".*" + JMHSample_18_Control.class.getSimpleName() + ".*")
+                .warmupIterations(1)
+                .measurementIterations(5)
+                .threads(2)
+                .forks(1)
+                .build();
+
+        new Runner(opt).run();
+    }
+
 }
--- a/jmh-samples/src/main/java/org/openjdk/jmh/samples/JMHSample_20_Annotations.java	Thu Jan 23 00:20:04 2014 +0400
+++ b/jmh-samples/src/main/java/org/openjdk/jmh/samples/JMHSample_20_Annotations.java	Thu Jan 23 02:03:41 2014 +0400
@@ -31,6 +31,10 @@
 import org.openjdk.jmh.annotations.Scope;
 import org.openjdk.jmh.annotations.State;
 import org.openjdk.jmh.annotations.Warmup;
+import org.openjdk.jmh.runner.Runner;
+import org.openjdk.jmh.runner.RunnerException;
+import org.openjdk.jmh.runner.options.Options;
+import org.openjdk.jmh.runner.options.OptionsBuilder;
 
 import java.util.concurrent.TimeUnit;
 
@@ -63,14 +67,26 @@
     }
 
     /*
-     * HOW TO RUN THIS TEST:
+     * ============================== HOW TO RUN THIS TEST: ====================================
      *
-     * You can run this test with:
+     * Note JMH honors the default annotation settings. You can always override
+     * the defaults via the command line or API.
+     *
+     * You can run this test:
+     *
+     * a) Via the command line:
      *    $ mvn clean install
      *    $ java -jar target/microbenchmarks.jar ".*JMHSample_20.*"
      *
-     * Note JMH honors the default annotation settings. You can always override
-     * the defaults via the command line.
+     * b) Via the Java API:
      */
 
+    public static void main(String[] args) throws RunnerException {
+        Options opt = new OptionsBuilder()
+                .include(".*" + JMHSample_20_Annotations.class.getSimpleName() + ".*")
+                .build();
+
+        new Runner(opt).run();
+    }
+
 }
--- a/jmh-samples/src/main/java/org/openjdk/jmh/samples/JMHSample_21_ConsumeCPU.java	Thu Jan 23 00:20:04 2014 +0400
+++ b/jmh-samples/src/main/java/org/openjdk/jmh/samples/JMHSample_21_ConsumeCPU.java	Thu Jan 23 02:03:41 2014 +0400
@@ -29,6 +29,10 @@
 import org.openjdk.jmh.annotations.Mode;
 import org.openjdk.jmh.annotations.OutputTimeUnit;
 import org.openjdk.jmh.logic.BlackHole;
+import org.openjdk.jmh.runner.Runner;
+import org.openjdk.jmh.runner.RunnerException;
+import org.openjdk.jmh.runner.options.Options;
+import org.openjdk.jmh.runner.options.OptionsBuilder;
 
 import java.util.concurrent.TimeUnit;
 
@@ -109,14 +113,29 @@
     }
 
     /*
-     * HOW TO RUN THIS TEST:
+     * ============================== HOW TO RUN THIS TEST: ====================================
      *
-     * You can run this test with:
+     * Note the single token is just a few cycles, and the more tokens
+     * you request, then more work is spent (almost linearly)
+     *
+     * You can run this test:
+     *
+     * a) Via the command line:
      *    $ mvn clean install
      *    $ java -jar target/microbenchmarks.jar ".*JMHSample_21.*" -w 1 -i 5 -f 1
      *
-     * Note the single token is just a few cycles, and the more tokens
-     * you request, then more work is spent (almost linerarly)
+     * b) Via the Java API:
      */
 
+    public static void main(String[] args) throws RunnerException {
+        Options opt = new OptionsBuilder()
+                .include(".*" + JMHSample_21_ConsumeCPU.class.getSimpleName() + ".*")
+                .warmupIterations(1)
+                .measurementIterations(5)
+                .forks(1)
+                .build();
+
+        new Runner(opt).run();
+    }
+
 }
--- a/jmh-samples/src/main/java/org/openjdk/jmh/samples/JMHSample_22_FalseSharing.java	Thu Jan 23 00:20:04 2014 +0400
+++ b/jmh-samples/src/main/java/org/openjdk/jmh/samples/JMHSample_22_FalseSharing.java	Thu Jan 23 02:03:41 2014 +0400
@@ -34,6 +34,10 @@
 import org.openjdk.jmh.annotations.Scope;
 import org.openjdk.jmh.annotations.State;
 import org.openjdk.jmh.annotations.Warmup;
+import org.openjdk.jmh.runner.Runner;
+import org.openjdk.jmh.runner.RunnerException;
+import org.openjdk.jmh.runner.options.Options;
+import org.openjdk.jmh.runner.options.OptionsBuilder;
 
 import java.util.concurrent.TimeUnit;
 
@@ -213,13 +217,26 @@
     }
 
     /*
-     * HOW TO RUN THIS TEST:
+     * ============================== HOW TO RUN THIS TEST: ====================================
      *
-     * You can run this test with:
+     * Note the slowdowns.
+     *
+     * You can run this test:
+     *
+     * a) Via the command line:
      *    $ mvn clean install
      *    $ java -jar target/microbenchmarks.jar ".*JMHSample_22.*" -t $CPU
      *
-     * Note the slowdowns.
+     * b) Via the Java API:
      */
 
+    public static void main(String[] args) throws RunnerException {
+        Options opt = new OptionsBuilder()
+                .include(".*" + JMHSample_22_FalseSharing.class.getSimpleName() + ".*")
+                .threads(Runtime.getRuntime().availableProcessors())
+                .build();
+
+        new Runner(opt).run();
+    }
+
 }
--- a/jmh-samples/src/main/java/org/openjdk/jmh/samples/JMHSample_23_AuxCounters.java	Thu Jan 23 00:20:04 2014 +0400
+++ b/jmh-samples/src/main/java/org/openjdk/jmh/samples/JMHSample_23_AuxCounters.java	Thu Jan 23 02:03:41 2014 +0400
@@ -34,6 +34,10 @@
 import org.openjdk.jmh.annotations.Setup;
 import org.openjdk.jmh.annotations.State;
 import org.openjdk.jmh.annotations.Warmup;
+import org.openjdk.jmh.runner.Runner;
+import org.openjdk.jmh.runner.RunnerException;
+import org.openjdk.jmh.runner.options.Options;
+import org.openjdk.jmh.runner.options.OptionsBuilder;
 
 import java.util.concurrent.TimeUnit;
 
@@ -84,11 +88,23 @@
     }
 
     /*
-     * HOW TO RUN THIS TEST:
+     * ============================== HOW TO RUN THIS TEST: ====================================
      *
-     * You can run this test with:
+     * You can run this test:
+     *
+     * a) Via the command line:
      *    $ mvn clean install
      *    $ java -jar target/microbenchmarks.jar ".*JMHSample_23.*"
+     *
+     * b) Via the Java API:
      */
 
+    public static void main(String[] args) throws RunnerException {
+        Options opt = new OptionsBuilder()
+                .include(".*" + JMHSample_23_AuxCounters.class.getSimpleName() + ".*")
+                .build();
+
+        new Runner(opt).run();
+    }
+
 }
--- a/jmh-samples/src/main/java/org/openjdk/jmh/samples/JMHSample_24_Inheritance.java	Thu Jan 23 00:20:04 2014 +0400
+++ b/jmh-samples/src/main/java/org/openjdk/jmh/samples/JMHSample_24_Inheritance.java	Thu Jan 23 02:03:41 2014 +0400
@@ -25,7 +25,6 @@
 package org.openjdk.jmh.samples;
 
 import org.openjdk.jmh.annotations.BenchmarkMode;
-import org.openjdk.jmh.annotations.CompilerControl;
 import org.openjdk.jmh.annotations.Fork;
 import org.openjdk.jmh.annotations.GenerateMicroBenchmark;
 import org.openjdk.jmh.annotations.Measurement;
@@ -34,6 +33,10 @@
 import org.openjdk.jmh.annotations.Scope;
 import org.openjdk.jmh.annotations.State;
 import org.openjdk.jmh.annotations.Warmup;
+import org.openjdk.jmh.runner.Runner;
+import org.openjdk.jmh.runner.RunnerException;
+import org.openjdk.jmh.runner.options.Options;
+import org.openjdk.jmh.runner.options.OptionsBuilder;
 
 import java.util.concurrent.TimeUnit;
 
@@ -97,11 +100,23 @@
     }
 
     /*
-     * HOW TO RUN THIS TEST:
+     * ============================== HOW TO RUN THIS TEST: ====================================
      *
-     * You can run this test with:
+     * You can run this test:
+     *
+     * a) Via the command line:
      *    $ mvn clean install
      *    $ java -jar target/microbenchmarks.jar ".*JMHSample_24.*"
+     *
+     * b) Via the Java API:
      */
 
+    public static void main(String[] args) throws RunnerException {
+        Options opt = new OptionsBuilder()
+                .include(".*" + JMHSample_24_Inheritance.class.getSimpleName() + ".*")
+                .build();
+
+        new Runner(opt).run();
+    }
+
 }