Rationalize benchmark setup and time units

* Make sure that all the benchmarks run using "gradle jmh"
* Make sure that each has a reasonable default time unit
* Add a way to change which benchmarks run via the command-line
* Add a README for the benchmarks

benchmarks/README.md

@@ -0,0 +1,54 @@
+# Rhino Benchmarks
+
+This directory contains a collection of various benchmarks that have been added to the Rhino
+project over the years. They have all been collected here and run using the JMH framework.
+
+## Running the Benchmarks
+
+To run all the benchmarks that exist, simply run, from the top-level directory:
+
+    ./gradlew jmh
+
+In addition, the environment variable BENCHMARK may be used to restrict which benchmarks are
+run -- it is a regular expression that matches the names of the benchmarks. 
+
+For example, to run only the SunSpider and V8 benchmarks, you can run:
+
+    BENCHMARK=V8|SunSpider ./gradlew jmh
+
+Running all the benchmarks takes about half an hour, so this is a valuable thing to do!
+
+## How the Benchmarks work
+
+Java, with its just-in-time compilation pipeline, bytecode generation in Rhino, and
+Java's super-complex garbage collector, is sensitive to warm up time and as a result, Rhino has 
+more variation between runs than other JavaScript engines. To get a repeatable result, we use
+the JMH framework, which runs each benchmark many times and does other "black hole" protection
+operations to try and get an accurate result. For this reason, these benchmarks take a lot longer
+to run than your favorite on-line JavaScript benchmarking web site.
+
+The purpose of these benchmarks has historically been to make Rhino perform better in server-side
+environments, so they all run at the maximum optimization level (9). Since so many people also
+use Rhino in interpreted mode, if there's an interest in benchmarking that too then we can
+always adjust these tests.
+
+## Benchmark Notes
+
+Here are a few notes on the specific benchmarks:
+
+* **SunSpiderBenchmark**: These are the venerable JavaScript benchmarks that have been used
+for a long time. They test both low-level operations like math operations, as well as higher-level
+tasks.
+* **V8Benchmark**: These are Google's V8 benchmarks, which may have been created to show how 
+efficient V8 is. They are still a good way to show how far we have to go.
+* **SlotMapBenchmark**: This is a low-level benchmark of the various SlotMap types in Rhino.
+Tiny changes in SlotMap performance affect property access in Rhino and translate into big
+changes in the other benchmarks.
+* **PropertyBenchmark**: This is a micro-benchmark that uses JavaScript code to test the efficiency
+of object property access.
+* **ObjectBenchmark**: These serve a similar purpose to PropertyBenchmark and perhaps we should
+have deleted these by now.
+* **BuiltinBenchmark**: This tries to measure the relative performance of the various ways to create
+native JavaScript objects in Java -- the reflection-based method, the IdScriptableObject that is used
+for many internal objects, and lambda functions.
+* **MathBenchmark**: This is a vehicle for quickly testing low-level math operations.

benchmarks/build.gradle

@@ -9,13 +9,13 @@ dependencies {
 }
 
 jmh {
-    // use this to include only some
-    //includes = ['SlotMap']
+    if (System.getenv('BENCHMARK') != null) {
+      includes = [System.getenv('BENCHMARK')]
+    }
     benchmarkMode = ['avgt']
     fork = 1
-    //timeUnit = 'ns'
-    iterations = 3
-    timeOnIteration = '5s'
+    iterations = 5
+    timeOnIteration = '2s'
     warmupIterations = 3
     warmup = '5s'
 }

benchmarks/src/jmh/java/org/mozilla/javascript/benchmarks/BuiltinBenchmark.java

@@ -1,6 +1,7 @@
 package org.mozilla.javascript.benchmarks;
 
 import java.lang.reflect.InvocationTargetException;
+import java.util.concurrent.TimeUnit;
 import org.mozilla.javascript.Context;
 import org.mozilla.javascript.IdFunctionObject;
 import org.mozilla.javascript.IdScriptableObject;
@@ -13,8 +14,8 @@
 import org.mozilla.javascript.annotations.*;
 import org.openjdk.jmh.annotations.*;
 
+@OutputTimeUnit(TimeUnit.MICROSECONDS)
 public class BuiltinBenchmark {
-
     @State(Scope.Thread)
     public static class AbstractClassState {
 

benchmarks/src/jmh/java/org/mozilla/javascript/benchmarks/MathBenchmark.java

@@ -2,13 +2,15 @@
 
 import java.io.FileReader;
 import java.io.IOException;
+import java.util.concurrent.TimeUnit;
 import org.mozilla.javascript.Context;
 import org.mozilla.javascript.Function;
 import org.mozilla.javascript.ScriptRuntime;
 import org.mozilla.javascript.Scriptable;
 import org.mozilla.javascript.ScriptableObject;
 import org.openjdk.jmh.annotations.*;
 
+@OutputTimeUnit(TimeUnit.NANOSECONDS)
 public class MathBenchmark {
     @State(Scope.Thread)
     public static class MathState {

benchmarks/src/jmh/java/org/mozilla/javascript/benchmarks/ObjectBenchmark.java

@@ -3,13 +3,15 @@
 import java.io.FileReader;
 import java.io.IOException;
 import java.util.Random;
+import java.util.concurrent.TimeUnit;
 import org.mozilla.javascript.Context;
 import org.mozilla.javascript.Function;
 import org.mozilla.javascript.Scriptable;
 import org.mozilla.javascript.ScriptableObject;
 import org.mozilla.javascript.tools.shell.Global;
 import org.openjdk.jmh.annotations.*;
 
+@OutputTimeUnit(TimeUnit.MICROSECONDS)
 public class ObjectBenchmark {
     static final Random rand = new Random();
 

benchmarks/src/jmh/java/org/mozilla/javascript/benchmarks/PropertyBenchmark.java

@@ -2,13 +2,15 @@
 
 import java.io.FileReader;
 import java.io.IOException;
+import java.util.concurrent.TimeUnit;
 import org.mozilla.javascript.Context;
 import org.mozilla.javascript.Function;
 import org.mozilla.javascript.ScriptRuntime;
 import org.mozilla.javascript.Scriptable;
 import org.mozilla.javascript.ScriptableObject;
 import org.openjdk.jmh.annotations.*;
 
+@OutputTimeUnit(TimeUnit.NANOSECONDS)
 public class PropertyBenchmark {
     @State(Scope.Thread)
     public static class PropertyState {

benchmarks/src/jmh/java/org/mozilla/javascript/benchmarks/SlotMapBenchmark.java

@@ -1,12 +1,14 @@
 package org.mozilla.javascript.benchmarks;
 
 import java.util.Random;
+import java.util.concurrent.TimeUnit;
 import org.mozilla.javascript.EmbeddedSlotMap;
 import org.mozilla.javascript.HashSlotMap;
 import org.mozilla.javascript.Slot;
 import org.mozilla.javascript.SlotMap;
 import org.openjdk.jmh.annotations.*;
 
+@OutputTimeUnit(TimeUnit.NANOSECONDS)
 public class SlotMapBenchmark {
     // Fixed seed for repeatability
     private static final Random rand = new Random(0);