changeset 901:16caa87c4b0d

Rephrase @Level Javadocs.
author shade
date Wed, 09 Jul 2014 18:56:08 +0400
parents fbccf73cf083
children 7811fb328a4c
files jmh-core/src/main/java/org/openjdk/jmh/annotations/Level.java
diffstat 1 files changed, 29 insertions(+), 26 deletions(-) [+]
line wrap: on
line diff
--- a/jmh-core/src/main/java/org/openjdk/jmh/annotations/Level.java	Wed Jul 09 15:47:48 2014 +0400
+++ b/jmh-core/src/main/java/org/openjdk/jmh/annotations/Level.java	Wed Jul 09 18:56:08 2014 +0400
@@ -28,56 +28,59 @@
  * Control when to run the fixture methods.
  *
  * @see org.openjdk.jmh.annotations.Setup
- * @see org.openjdk.jmh.annotations.TearDown
+ * @see TearDown
  */
 public enum Level {
 
     /**
      * Trial level: to be executed before/after each run of the benchmark.
      *
-     * Trial is the set of benchmark iterations.
+     * <p>Trial is the set of benchmark iterations.</p>
      */
     Trial,
 
     /**
      * Iteration level: to be executed before/after each iteration of the benchmark.
      *
-     * Iteration is the set of benchmark invocations.
+     * <p>Iteration is the set of benchmark invocations.</p>
      */
     Iteration,
 
     /**
      * Invocation level: to be executed for each benchmark method execution.
      *
-     * WARNING: HERE BE DRAGONS!
+     * <p><b>WARNING: HERE BE DRAGONS! THIS IS A SHARP TOOL.
      * MAKE SURE YOU UNDERSTAND THE REASONING AND THE IMPLICATIONS
-     * OF THE WARNINGS BELOW BEFORE EVEN CONSIDERING USING THIS LEVEL.
+     * OF THE WARNINGS BELOW BEFORE EVEN CONSIDERING USING THIS LEVEL.</b></p>
      *
-     * It is almost never a good idea to use this in nano- and micro-benchmarks.
+     * <p>This level is only usable for benchmarks taking more than a millisecond
+     * per single {@link Benchmark} method invocation. It is a good idea to validate
+     * the impact for your case on ad-hoc basis as well.</p>
      *
-     * <p>WARNING #1: In order to subtract the helper time from the
-     * benchmark itself, we will have to have at least two timestamps
-     * per *each* benchmark invocation. If the benchmarked method is
-     * small, then we saturate the system with timestamp requests, which
-     * *both* make timestamp requests the critical part of the benchmark
-     * time, and inhibit workload scalability, introducing the artificial
-     * scalability bottleneck.</p>
+     * <p>WARNING #1: Since we have to subtract the setup/teardown costs from
+     * the benchmark time, on this level, we have to timestamp *each* benchmark
+     * invocation. If the benchmarked method is small, then we saturate the
+     * system with timestamp requests, which introduce artificial latency,
+     * throughput, and scalability bottlenecks.</p>
      *
-     * <p>Also, the hiccups in measurement can be hidden from these individual
-     * timing measurement, which can introduce inconsistent results. The largest
-     * caveat is measuring oversaturated system where the descheduling events
-     * will be missed, and the benchmark will perceive the fictionally large
-     * throughput.</p>
+     * <p>WARNING #2: Since we measure individual invocation timings with this
+     * level, we probably set ourselves up for (coordinated) omission. That means
+     * the hiccups in measurement can be hidden from timing measurement, and
+     * can introduce surprising results. For example, when we use timings to
+     * understand the benchmark throughput, the omitted timing measurement will
+     * result in lower aggregate time, and fictionally *larger* throughput.</p>
      *
-     * <p>WARNING #2: In order to maintain the basic interference behavior
-     * of other Levels (e.g. the State(Scope.Benchmark) should only fire the
-     * helper method once per invocation, regardless of the thread count),
-     * we have to arbitrate the access to the state between worker thread,
-     * and do that on *critical path*, thus further offsetting the measurement.</p>
+     * <p>WARNING #3: In order to maintain the same sharing behavior as other
+     * Levels, we sometimes have to synchronize (arbitrage) the access to
+     * {@link State} objects. Other levels do this outside the measurement,
+     * but at this level, we have to synchronize on *critical path*, further
+     * offsetting the measurement.</p>
      *
-     * <p>WARNING #3: Current implementation in JMH allows the helper method
-     * execution to overlap with the benchmark method itself in order to simplify
-     * arbitrage. (To be redefined in future).</p>
+     * <p>WARNING #4: Current implementation allows the helper method execution
+     * at this Level to overlap with the benchmark invocation itself in order
+     * to simplify arbitrage. That matters in multi-threaded benchmarks, when
+     * one worker thread executing {@link Benchmark} method may observe other
+     * worker thread already calling {@link TearDown} for the same object.</p>
      */
     Invocation,
 }