Code Tools: jmh
JMH is a Java harness for building, running, and analysing nano/micro/milli/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 an alternative JVM language, use another archetypeArtifactId from the list of existing ones. Using alternative archetypes may require additional changes in the build configuration, see the$ mvn archetype:generate \ -DinteractiveMode=false \ -DarchetypeGroupId=org.openjdk.jmh \ -DarchetypeArtifactId=jmh-java-benchmark-archetype \ -DgroupId=org.sample \ -DartifactId=test \ -Dversion=1.0
pom.xmlin the generated project. After the project is generated, you can build it:
$ 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 dependencies versions 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
Getting SupportMake sure you did this before publishing the benchmark, and/or requesting the JMH feature:
- JMH annotations Javadocs and Samples are essential reading. Follow the JMH samples to get familiar with the API, use cases, culprits, and pitfalls in building the microbenchmarks and using JMH.
- Your benchmarks should be peer-reviewed. Do not assume that a nice harness will magically free you from considering benchmarking pitfalls. We only promise to make avoiding them easier, not avoiding them completely.
- Archetypes provide the golden build configuration. Try to generate the clean JMH benchmark project 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.
- Current development code is usually leaner, meaner, and better. Try to run with bleeding edge JMH to see if the issue is already fixed.
- Some things may be puzzling, but perfectily legitimate. 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.