Extra javadoc & less dead code

simulation/src/main/java/com/palantir/dialogue/core/Benchmark.java

@@ -39,12 +39,16 @@
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
+/**
+ * Exercises the given {@link Channel} using a pre-defined number of requests, all scheduled on the
+ * {@link Simulation} executor.
+ */
 public final class Benchmark {
     private static final Logger log = LoggerFactory.getLogger(Benchmark.class);
-    public static String REQUEST_ID_HEADER = "simulation-req-id";
+    static final String REQUEST_ID_HEADER = "simulation-req-id";
 
     private Simulation simulation;
-    private Channel channel;
+    private Channel channelUnderTest;
     private Duration delayBetweenRequests;
     private Stream<ScheduledRequest> requestStream;
     private Function<Long, Request> requestSupplier = Benchmark::constructRequest;
@@ -97,7 +101,7 @@ public Benchmark simulation(Simulation sim) {
     }
 
     public Benchmark channel(Channel value) {
-        channel = value;
+        channelUnderTest = value;
         return this;
     }
 
@@ -138,7 +142,7 @@ public BenchmarkResult run() {
 
     @SuppressWarnings("FutureReturnValueIgnored")
     public ListenableFuture<BenchmarkResult> schedule() {
-        HistogramChannel histogramChannel = new HistogramChannel(simulation, channel);
+        HistogramChannel histogramChannel = new HistogramChannel(simulation, channelUnderTest);
 
         long[] requestsStarted = {0};
         long[] responsesReceived = {0};
@@ -221,15 +225,22 @@ interface BenchmarkResult {
         long numReceived();
     }
 
+    /**
+     * Determines when the benchmark terminates - useful when a server is behaving like a black hole (not returning).
+     */
     interface ShouldStopPredicate {
+        /** Called once to set up a future - when this resolves, the benchmark will stop. */
         SettableFuture<Void> getFuture();
 
+        /**
+         * Called after every request to give this predicate the opportunity to terminate the benchmark by
+         * resolving the SettableFuture.
+         */
         void update(Duration time, long requestsStarted, long responsesReceived);
     }
 
     @Value.Immutable
     interface ScheduledRequest {
-
         Endpoint ENDPOINT = SimulationUtils.endpoint("endpoint");
 
         long number();

simulation/src/main/java/com/palantir/dialogue/core/HistogramChannel.java

@@ -28,7 +28,7 @@
 
 final class HistogramChannel implements Channel {
     private final Simulation simulation;
-    private final Histogram histogram; // beware unit is nanos!
+    private final Histogram histogram;
     private final Channel channel;
 
     HistogramChannel(Simulation simulation, Channel channel) {
@@ -37,6 +37,7 @@ final class HistogramChannel implements Channel {
         histogram = new Histogram(new SlidingTimeWindowArrayReservoir(1, TimeUnit.DAYS, simulation.codahaleClock()));
     }
 
+    /** Unit is nanos. */
     public Histogram getHistogram() {
         return histogram;
     }

simulation/src/main/java/com/palantir/dialogue/core/Simulation.java

@@ -27,9 +27,8 @@
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
-/** Combined ScheduledExecutorService and Clock. */
+/** Combined ScheduledExecutorService and Clock. All tasks get executed on the main thread. */
 final class Simulation {
-
     private static final Logger log = LoggerFactory.getLogger(Simulation.class);
 
     private final DeterministicScheduler deterministicExecutor = new DeterministicScheduler();

simulation/src/main/java/com/palantir/dialogue/core/SimulationMetrics.java

@@ -51,7 +51,7 @@
 
 /**
  * This is a combination metric registry, reporter, logger and renderer, all hooked up to
- * {@link Simulation#clock()}.
+ * {@link Simulation#clock()}. Capable of reporting PNGs (although this is slow).
  */
 final class SimulationMetrics {
     private static final Logger log = LoggerFactory.getLogger(SimulationMetrics.class);

simulation/src/main/java/com/palantir/dialogue/core/SimulationServer.java

@@ -37,6 +37,11 @@
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
+/**
+ * A fake 'server' which just schedules responses on the {@link Simulation} executor.
+ * Responses are produced by the first {@link ServerHandler} that returns a future - these can be used to change
+ * behaviour at different times points (e.g. a fast handler until 3 seconds, then a slow handler after).
+ */
 final class SimulationServer implements Channel {
     private static final Logger log = LoggerFactory.getLogger(SimulationServer.class);
 

simulation/src/main/java/com/palantir/dialogue/core/SimulationUtils.java

@@ -24,30 +24,10 @@
 import com.palantir.dialogue.UrlBuilder;
 import java.io.ByteArrayInputStream;
 import java.io.InputStream;
-import java.util.ArrayList;
-import java.util.Collections;
 import java.util.List;
 import java.util.Map;
-import java.util.Random;
 
-public final class SimulationUtils {
-
-    public static Randomness newPseudoRandom() {
-        return new Randomness() {
-            private final Random random = new Random(12345L);
-
-            @Override
-            public <T> List<T> shuffle(List<T> list) {
-                if (list.size() == 1 || list.isEmpty()) {
-                    return list;
-                }
-
-                List<T> shuffleMe = new ArrayList<>(list);
-                Collections.shuffle(shuffleMe, random);
-                return shuffleMe;
-            }
-        };
-    }
+final class SimulationUtils {
 
     public static Response response(int status, String version) {
         return new Response() {

simulation/src/test/java/com/palantir/dialogue/core/SimulationTest.java

@@ -48,8 +48,8 @@
 
 /**
  * Simulates client heuristics defined in {@link Strategy} against {@link SimulationServer} nodes. These don't
- * actually bind to ports, they just schedule responses to return at some point. All scheduling happens on a
- * deterministic scheduler in {@link Simulation}, so hours of requests can be simulated instantly.
+ * actually bind to ports, they just schedule responses to return at some point. All scheduling happens on the
+ * deterministic scheduler in {@link Simulation} (on the main thread), so hours of requests can be simulated instantly.
  *
  * These simulations only reveal characteristics and emergent behaviour of the clients - they can't be used to
  * compare how efficient (in terms of CPU or allocations) clients are - a dedicated microbenchmarking harness should

simulation/src/test/java/com/palantir/dialogue/core/Strategy.java

@@ -79,7 +79,9 @@ private static LimitedChannel instrumentClient(LimitedChannel delegate, Simulati
 
             @Override
             public Optional<ListenableFuture<Response>> maybeExecute(Endpoint endpoint, Request request) {
-                log.debug("starting request={}", request.headerParams().get(Benchmark.REQUEST_ID_HEADER).get(0));
+                log.debug(
+                        "starting request={}",
+                        request.headerParams().get(Benchmark.REQUEST_ID_HEADER).get(0));
                 starts.mark();
                 Optional<ListenableFuture<Response>> response = delegate.maybeExecute(endpoint, request);
                 if (!response.isPresent()) {