Minor updates to developer docs CTR
Project: http://git-wip-us.apache.org/repos/asf/incubator-tinkerpop/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-tinkerpop/commit/7f2be972 Tree: http://git-wip-us.apache.org/repos/asf/incubator-tinkerpop/tree/7f2be972 Diff: http://git-wip-us.apache.org/repos/asf/incubator-tinkerpop/diff/7f2be972 Branch: refs/heads/TINKERPOP-1331 Commit: 7f2be972fdcba266819bb17691ccbd55fdd064d2 Parents: af98ba1 Author: Stephen Mallette <sp...@genoprime.com> Authored: Wed Jun 8 09:52:40 2016 -0400 Committer: Stephen Mallette <sp...@genoprime.com> Committed: Wed Jun 8 09:52:40 2016 -0400 ---------------------------------------------------------------------- .../developer/development-environment.asciidoc | 3 +- docs/src/dev/developer/for-committers.asciidoc | 32 +++++++++++++++++++- 2 files changed, 33 insertions(+), 2 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-tinkerpop/blob/7f2be972/docs/src/dev/developer/development-environment.asciidoc ---------------------------------------------------------------------- diff --git a/docs/src/dev/developer/development-environment.asciidoc b/docs/src/dev/developer/development-environment.asciidoc index 3bb6613..70e0dcd 100644 --- a/docs/src/dev/developer/development-environment.asciidoc +++ b/docs/src/dev/developer/development-environment.asciidoc @@ -50,6 +50,7 @@ mvn -Dmaven.javadoc.skip=true --projects tinkergraph-gremlin test ** Execute with the `-DincludeNeo4j` option to include transactional tests. ** Execute with the `-DuseEpoll` option to try to use Netty native transport (works on Linux, but will fallback to Java NIO on other OS). * Performance Tests: `mvn verify -DskipPerformanceTests=false` +* Benchmarks: `mvn verify -DskipBenchmarks=false` [[docker-integration]] Docker Integration @@ -95,4 +96,4 @@ Developers working on the `neo4j-gremlin` module should enabled the `include-neo This will ensure that tests will properly execute within the IDE. If Intellij complains about "duplicate sources" for the Groovy files when attempting to compile/run tests, then -install the link:http://plugins.jetbrains.com/plugin/7442?pr=idea[GMavenPlus Intellij plugin]. +install the link:http://plugins.jetbrains.com/plugin/7442?pr=idea[GMavenPlus Intellij plugin]. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/incubator-tinkerpop/blob/7f2be972/docs/src/dev/developer/for-committers.asciidoc ---------------------------------------------------------------------- diff --git a/docs/src/dev/developer/for-committers.asciidoc b/docs/src/dev/developer/for-committers.asciidoc index 49f1899..d44c6cf 100644 --- a/docs/src/dev/developer/for-committers.asciidoc +++ b/docs/src/dev/developer/for-committers.asciidoc @@ -200,6 +200,36 @@ When writing a test case for a Gremlin step, be sure to use the following conven ** `checkResults(Arrays.asList("marko","josh"), traversal)` ** `checkMap(new HashMap<String,Long>() {{ put("marko",1l); }}, traversal.next())` +Developing Benchmarks +--------------------- + +Benchmarks are a useful tool to track performance between TinkerPop versions and also as tools to aid development +decision making. TinkerPop uses link:http://openjdk.java.net/projects/code-tools/jmh/[OpenJDK JMH] for benchmark development. +The JMH framework provides tools for writing robust benchmarking code that avoid many of the pitfalls inherent in benchmarking +JIT compiled code on the JVM. Example JMH benchmarks can be found +link:http://hg.openjdk.java.net/code-tools/jmh/file/tip/jmh-samples/src/main/java/org/openjdk/jmh/samples/[here]. + +TinkerPop benchmarks live in the `gremlin-benchmark` module and can either be run from within your IDE or as a standalone +uber-jar. The uber-jar is the JMH recommended approach and also makes it easy to distribute artifacts to various environments +to gather benchmarking numbers. Having said that, in most cases it should be sufficient to run it from within the IDE. + +Benchmarks will not run by default because they are time consuming. To enable benchmarks during the test phase do +`-DskipBenchmarks=false`. To change the number of warmup iterations, measurement iterations, and forks you can do +`mvn clean test -DskipBenchmarks=false -DdefaultForks=5 -DmeasureIterations=20 -DwarmupIterations=20`. Benchmark results +will be output by default to the `benchmarks` directory in JSON format. + +Benchmarks may also be run from the command line using the JMH runner. Build the uber-jar and simply run +`java -jar gremlin-benchmark-TP-VERSION.jar`. To see a list of JMH runner options, add the `-h` flag. + +The JUnit/JMH integration was inspired by the Netty projects microbenchmarking suite. Please refer to the Netty +link:http://netty.io/wiki/microbenchmarks.html[docs] for more details. Presently there are 3 abstract benchmark classes +that may be used as building blocks for your benchmarks; `AbstractBenchmarkBase`, `AbstractGraphBenchmark`, and +`AbstractGraphMutateBenchmark`. + +* `AbstractBenchmarkBase` - extend when your benchmark does not require a graph instance +* `AbstractGraphBenchmark` - extend when you are benchmarking read operations against a graph +* `AbstractGraphMutateBenchmark` - extend when you are benchmarking graph mutation operations eg. `g.addV()`, `graph.addVertex()` + [[rtc]] Review then Commit ------------------ @@ -361,4 +391,4 @@ for debugging purposes within tests can be altered by editing the `log4j-test.pr resources. That file gets copied to the `target/test-classes` on build and surefire and failsafe plugins in maven are then configured to point at that area of the file system for those configuration files. The properties files can be edited to fine tune control of the log output, but generally speaking the current configuration is likely -best for everyone's general purposes, so if changes are made please revert them prior to commit. +best for everyone's general purposes, so if changes are made please revert them prior to commit. \ No newline at end of file
