= Disruptor Performance Tests

:Author: LMAX Development Team
:Email:
:Date: {docdata}

== Run the performance tests

When making changes to the Disruptor it is important to be aware of the performance impact of your change.

To measure the performance characteristics of the Disruptor there are many tests in the `perftest` and `jmh` sourcesets.

=== Running Perf Tests

The perf tests are all under `src/perftest` and are built using a custom framework.

To run them you need to fist build the perf jar and then run a single test at a time, for example:

[source,shell script]
----
$ ./gradlew perfJar
$ java -cp build/libs/disruptor-perf-*.jar com.lmax.disruptor.sequenced.OneToOneSequencedThroughputTest
----

=== Running JMH Tests

There are also https://github.com/openjdk/jmh/[JMH Benchmarks] for testing the performance of the Disruptor, these can be run with a gradle command

[source,shell script]
----
$ ./gradlew jmh
----

==== Isolated CPU benchmarking

Some JMH Benchmarks can be run on machines with isolated cpus to get results with less error.

Build the `jmhJar` on your development machine and transfer it to your benchmarking machine with isolated cpus:

[source,shell script]
----
dev-machine /path/to/disruptor $ ./gradlew jmhJar
dev-machine /path/to/disruptor $ scp dev-machine:build/lib/disruptor-*-jmh.jar bench-machine:
----

Assuming a system set up with isolated cores, e.g.

[source,shell script]
----
bench-machine ~ $ cat /proc/cmdline
... isolcpus=31,33,35,37,39,41,43,45,47,7,9,11,13,15,17,19,21,23 nohz_full=31,33,35,37,39,41,43,45,47,7,9,11,13,15,17,19,21,23 ...
----

And the system may have a `cpuset` setup to split application threads from sharing cpus with kernel code:

[source,shell script]
----
bench-machine ~ $ cat /cpusets/app/cpus
5,7-23,29,31-47
----

You can run the benchmarks taskset to some of those cpus so that Java threads (like GC and complication) run on some cores
and JMH Benchmark threads are pinned to isolated cpus using the following command (which is running just the one benchmark, `MultiProducersSequencerBenchmark`):

[source,shell script]
----
bench-machine ~ $ cat runBenchmarks.sh
#!/bin/bash
JAVA_HOME=/opt/jdk11/1.11.0.6_zulu11.37.17_ca-1
ISOLATED_CPUS=7,9,11,13,15,17,19,21,23 $JAVA_HOME/bin/java -jar ./disruptor-4.0.0-SNAPSHOT-jmh.jar -rf json -rff /tmp/jmh-result.json -foe true -v NORMAL -prof perf -jvmArgsPrepend -Xmx256m -jvmArgsPrepend -Xms256m -jvmArgsPrepend -XX:MaxDirectMemorySize=1g $@

bench-machine ~ $ sudo cset proc -v --exec app -- taskset -c 5,8,10,12,14,16,18,20,22,29,32,34,36,38,40,42,44,46 ./runBenchmarks.sh MultiProducersSequencerBenchmark
----
