changeset 950:606df305ada6

samples: rephrase two starting samples.
author shade
date Fri, 15 Aug 2014 13:58:40 +0400
parents f90aef7f1d2c
children 858587557d96
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
diffstat 2 files changed, 34 insertions(+), 27 deletions(-) [+]
line wrap: on
line diff
--- a/jmh-samples/src/main/java/org/openjdk/jmh/samples/JMHSample_01_HelloWorld.java	Thu Aug 14 12:28:02 2014 +0400
+++ b/jmh-samples/src/main/java/org/openjdk/jmh/samples/JMHSample_01_HelloWorld.java	Fri Aug 15 13:58:40 2014 +0400
@@ -35,14 +35,16 @@
     /*
      * This is our first benchmark method.
      *
-     * The contract for the benchmark methods is very simple:
-     * annotate it with @Benchmark, and you are set to go.
-     * JMH will run the test by continuously calling this method, and measuring
-     * the performance metrics for its execution.
+     * JMH works as follows: users annotated the methods with @Benchmark, and
+     * then JMH produces the generated code to run this particular benchmark
+     * as reliable as possible. In general, one might think about @Benchmark
+     * methods as the benchmark "payload", the things we want to measure.
+     * The surrounding infrastructure is provided by the harness itself.
      *
-     * The method names are non-essential, it matters they are marked with
-     * @Benchmark. You can have multiple benchmark methods
-     * within the same class.
+     * Read the Javadoc for @Benchmark annotation for complete semantics and
+     * restrictions. At this point, we only not that the methods names are
+     * non-essential, and it only matters the methods are marked with
+     * @Benchmark. You can have multiple benchmark methods within the same class.
      *
      * Note: if the benchmark method never finishes, then JMH run never
      * finishes as well. If you throw the exception from the method body,
--- a/jmh-samples/src/main/java/org/openjdk/jmh/samples/JMHSample_02_BenchmarkModes.java	Thu Aug 14 12:28:02 2014 +0400
+++ b/jmh-samples/src/main/java/org/openjdk/jmh/samples/JMHSample_02_BenchmarkModes.java	Fri Aug 15 13:58:40 2014 +0400
@@ -38,26 +38,31 @@
 public class JMHSample_02_BenchmarkModes {
 
     /*
-     * JMH generates lots of synthetic code for the benchmarks for
-     * you during the compilation. JMH can measure the methods in lots
-     * of modes, and it will generate all the needed code at once.
-     * Users may select the default benchmark mode with the special
-     * annotation, or select/override the mode via the command line.
+     * JMH generates lots of synthetic code for the benchmarks for you
+     * during the benchmark compilation. JMH can measure the benchmark
+     * methods in lots of modes. Users may select the default benchmark
+     * mode with the special annotation, or select/override the mode via
+     * the runtime options.
      *
-     * With this scenario, we start to measure something useful. Note
-     * that we can conveniently have the exception at the benchmark method,
-     * in order to reduce some of the clutter.
+     * With this scenario, we start to measure something useful. Note that
+     * our payload code potentially throws the exceptions, and we can just
+     * declare them to be thrown. If the code throws the actual exception,
+     * the benchmark execution will stop with error.
      *
-     * P.S. It is helping at times to look into the generated code trying
-     * to diagnose  the performance issue. You might see you don't measuring
-     * it right! The generated code for this particular sample is somewhere at
+     * When you are puzzled with some particular behavior, it usually helps
+     * to look into the generated code. You might see the code is doing not
+     * something you intend it to do. Good experiments always follow up on
+     * the experimental setup, and cross-checking the generated code is an
+     * important part of that follow up.
+     *
+     * The generated code for this particular sample is somewhere at
      *  target/generated-sources/annotations/.../JMHSample_02_BenchmarkModes.java
      */
 
     /*
-     * This benchmark type measures the raw throughput by continuously calling
-     * the benchmark method in the time-bound iteration, and counting how many
-     * times we executed the method.
+     * Mode.Throughput, as stated in its Javadoc, measures the raw throughput
+     * by continuously calling the benchmark method in a time-bound iteration,
+     * and counting how many times we executed the method.
      *
      * We are using the special annotation to select the units to measure in,
      * although you can use the default.
@@ -71,7 +76,7 @@
     }
 
     /*
-     * This benchmark type measures the average execution time, and it does it
+     * Mode.AverageTime measures the average execution time, and it does it
      * in the way similar to Mode.Throughput.
      *
      * Some might say it is the reciprocal throughput, and it really is.
@@ -86,10 +91,10 @@
     }
 
     /*
-     * This benchmark type samples the execution time. With this mode, we are
-     * still running the method in a time-bound iteration, but instead of measuring
-     * the total time, we periodically sample the time spent in *some* of the
-     * benchmark method calls.
+     * Mode.SampleTime samples the execution time. With this mode, we are
+     * still running the method in a time-bound iteration, but instead of
+     * measuring the total time, we measure the time spent in *some* of
+     * the * benchmark method calls.
      *
      * This allows us to infer the distributions, percentiles, etc.
      *
@@ -104,7 +109,7 @@
     }
 
     /*
-     * This benchmark type measures the single method invocation time. As the name
+     * Mode.SingleShotTime measures the single method invocation time. As the Javadoc
      * suggests, we do only the single benchmark method invocation. The iteration
      * time is meaningless in this mode: as soon as benchmark method stops, the
      * iteration is over.