help/jmh.txt

benchmarks
==========

The :lucene:benchmark-jmh module contains can be used to compile
and execute JMH (https://github.com/openjdk/jmh) micro-benchmarks.

Look at existing classes and JMH documentation for inspiration on how
to write good micro-benchmarks.

build
=====

To compile the project and prepare JMH launcher, run:

gradlew :lucene:benchmark-jmh:assemble

The above target will display exact commands to execute JMH from
command line.

run
===

java --module-path lucene/benchmark-jmh/build/benchmarks --module org.apache.lucene.benchmark.jmh

You can pass any JMH options to the above command, for example:

  -h               displays verbose help for all options
  -l               list available benchmarks
  -lp              list benchmarks that pass the filter and their parameters
  -prof perfasm    use perfasm profiler to see assembly
  -p size=1024     pass "size=1024" parameter to benchmark
  regexp           execute all benchmark containing regexp

Here is an example running a targeted benchmark:

java --module-path lucene/benchmark-jmh/build/benchmarks --module org.apache.lucene.benchmark.jmh VectorUtilBenchmark.binaryCosine -p size=1024

Or running all methods and sizes of VectorUtilBenchmark

java --module-path lucene/benchmark-jmh/build/benchmarks --module org.apache.lucene.benchmark.jmh VectorUtilBenchmark


hsdis setup
===========

Linux

In order to see disassembled instructions and not just binary instructions when using '-prof perfasm':

  $ git clone --depth 1 https://github.com/openjdk/jdk/
  $ curl -f https://ftp.gnu.org/gnu/binutils/binutils-2.38.tar.gz | tar -zxf -
  $ (cd jdk && bash ./configure --with-hsdis=binutils --with-binutils-src=../binutils-2.38 && make build-hsdis)
  $ cp jdk/build/linux-x86_64-server-release/support/hsdis/hsdis-amd64.so $JAVA_HOME/lib/server

Mac OS X

In order to see disassembled instructions and not just binary instructions when using '-prof dtraceasm':

This one is a little rough because they removed the Makefile so you have to bring it back from the dead.
Otherwise you are stuck wrestling down full dependencies of OpenJDK (metal etc) just to compile a single C file.
Also you must run benchmarks as root to use dtrace, but it works.

  $ git clone --depth 1 https://github.com/openjdk/jdk/
  $ curl -f https://ftp.gnu.org/gnu/binutils/binutils-2.38.tar.gz | tar -zxf -
  $ curl -fo jdk/src/utils/hsdis/binutils/Makefile https://raw.githubusercontent.com/openjdk/jdk/3c7ae1225f0d5575fd927a9b76fb40dc30e208cd/src/utils/hsdis/Makefile
  $ vi jdk/src/utils/hsdis/binutils/Makefile, change SOURCE = hsdis.c to SOURCE = hsdis-binutils.c
  $ vi jdk/src/utils/hsdis/binutils/hsdis-binutils.c, change #include "hsdis.h" to #include "../hsdis.h"
  $ (cd jdk/src/utils/hsdis/binutils && make BINUTILS=../../../../../binutils-2.38 ARCH=aarch64)
  $ cp jdk/src/utils/hsdis/binutils/build/macosx-aarch64/hsdis-aarch64.dylib $JAVA_HOME/lib/server