Code Tools: jmh
JMH is a Java harness for building, running, and analysing nano/micro/macro benchmarks written in Java and other languages targetting the JVM.
JMH is Maven-driven, hence having Maven installed will bring the best experience. Also, the working JDK installation should be available to build the project, the build will require the JAVA_HOME set to the correct JDK location. The rest of the page assumes we use Maven. However, there is the Ant sample, which describes how can one use JMH outside Maven world.
Basic usage: Released bundlesOpenJDK Community regularly publishes JMH artifacts and archetypes in Maven Central repository. This allows users to automatically set up JMH for their new projects. This command will generate the new JMH-driven project in test folder:
If you want to benchmark a non-Java JVM language, use another archetypeArtifactId from the list of existing ones. After the project is generated, you can build it:$ mvn archetype:generate \ -DinteractiveMode=false \ -DarchetypeGroupId=org.openjdk.jmh \ -DarchetypeArtifactId=jmh-java-benchmark-archetype \ -DgroupId=org.sample \ -DartifactId=test \ -Dversion=1.0
$ cd test/ $ mvn clean install
After the build is done, you will get the self-contained executable JAR, which holds your benchmark, and all essential JMH infrastructure code:
$ java -jar target/microbenchmarks.jar
Run with -h to see the command line options available.
If you have problems running with the current JMH version, or
archetype sets you up for an outdated JMH version, try to change
<version> tag in
pom.xml. Here is
the list of
Advanced usage: "Bleeding Edge"
In many cases, you want bleeding edge code which contains fixes, features, and APIs not available yet in released versions. This section explains how to get the "bleeding edge" JMH in your project.
- Check out JMH source with Mercurial:
$ hg clone http://hg.openjdk.java.net/code-tools/jmh/ jmh
- Build JMH. You can optionally skip the tests:
$ cd jmh/ $ mvn clean install -DskipTests
You only need to do this step once, and Maven will deploy JMH into Maven repo on your local machine.
If you already have the benchmark project, then it is enough to change JMH dependency version to
1.0-SNAPSHOT. If not, create the JMH benchmark project and change the version there.
Done! Build the benchmark project, and run it:
$ mvn clean install $ java -jar target/microbenchmarks.jar -h
Getting SupportMake sure you did this before publishing the benchmark, and/or requesting the JMH feature:
- Follow the "JMH samples" to get familiar with the API, use cases, culprits, and pitfalls in building the microbenchmarks and using JMH.
- Try to generate the clean JMH benchmark and transplant the benchmark there. This is important to try when upgrading to the newer JMH versions, since the minute differences in the build configurations may attribute to the failures you are seeing.
- Try to run with bleeding edge JMH to see if the issue is already fixed.
- Look around mailing list archives to see if the issue was discussed before.
If all these did not help, you are welcome at the JMH mailing list.