JMH: Write Correct Java Microbenchmarks

JMH (Java Microbenchmark Harness) is the OpenJDK project's tool for writing correct microbenchmarks. Reasoning about JVM performance by hand is hopeless — the JIT compiles, inlines, and eliminated code, and naive stopwatch loops get optimized to nothing. JMH handles warm-up, dead-code elimination, black-holes, and forking so your numbers mean something.

It runs from a standalone right-jar or via Maven/Gradle plugins. The golden rules: black-hole every result, warm up genuinely, and never draw conclusions you didn't measure.

Official JMH (Java Microbenchmark Harness) project

Scaffold a benchmark

JMH best works as a separate module or even a standalone main. The maven archetype is the fastest start.

mvn archetype:generate \
  -DarchetypeGroupId=org.openjdk.jmh \
  -DarchetypeArtifactId=jmh-java-11-archetype \
  -DgroupId=com.example -DartifactId=bench

A minimal benchmark

Annotate methods with @Benchmark. Use a Blackhole to consume results so the JIT cannot void them.

@Benchmark
@BenchmarkMode(Mode.Throughput)
@Fork(2)
@Warmup(iterations = 3, time = 1)
@Measurement(iterations = 5, time = 1)
public void sumLoop(Blackhole bh) {
  long acc = 0;
  for (int i = 0; i < 1000; i++) acc += i;
  bh.consume(acc);
}

Run and read

Run via the class with main (each @Benchmark is a separate measurement set). The output prints a score with the chosen Mode and unit (e.g., ops/ns for Throughput).

mvn package
java -jar target/benchmarks.jar

Blackhole — the rule you can't skip

A plain loop that returns nothing or whose result is unused is dead code the JIT removes. blackhole.consume(x) forces the result to be observed, and blackhole.consumeCPU(int) burns time to shape loop bodies without producing observable values.

Get productive in minutes

Measure a tiny method

Write, build, run.

@Benchmark public void twice(Blackhole bh) {
  bh.consume(computeDouble());
}

java -jar target/benchmarks.jar