Code Tools: jmh
The 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 in Maven Central repository. Among other things, this also enables us to automatically create the benchmark projects:
After the project is generated, you can build it:$ mvn archetype:generate \ -DinteractiveMode=false \ -DarchetypeGroupId=org.openjdk.jmh \ -DarchetypeArtifactId=jmh-simple-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 -h
Please follow the jmh samples to get familiar with the API, use cases, culprits, and pitfalls in building the microbenchmarks and using the jmh. Questions, reports, bugs can go to the jmh-dev@ mailing list.
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 the jmh source:
$ hg clone http://hg.openjdk.java.net/code-tools/jmh/ jmh
- Build the 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 your local repo. If you have the Maven repository manager installed, it might be a good idea to deploy the artifact there. If not, you can just go with the local build.
If you already have the benchmark project, then it is enough to change jmh dependency version to
1.0-SNAPSHOT. Otherwise, create the basic POM for your benchmark project, and follow the rest of this section.
- Reference the jmh-core dependency in benchmark project POM:
<dependency> <groupId>org.openjdk.jmh</groupId> <artifactId>jmh-core</artifactId> <version>1.0-SNAPSHOT</version> </dependency>
- Generate the self-contained JAR with Main-Class:
<plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-shade-plugin</artifactId> <executions> <execution> <phase>package</phase> <goals> <goal>shade</goal> </goals> <configuration> <finalName>microbenchmarks</finalName> <transformers> <transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer"> <mainClass>org.openjdk.jmh.Main</mainClass> </transformer> </transformers> </configuration> </execution> </executions> </plugin>
Done! Build the benchmark project, and run it:
$ mvn clean install $ java -jar target/microbenchmarks.jar -h