ExecutableTimer.java

/*
 * Strongback
 * Copyright 2015, Strongback and individual contributors by the @authors tag.
 * See the COPYRIGHT.txt in the distribution for a full listing of individual
 * contributors.
 *
 * Licensed under the MIT License; you may not use this file except in
 * compliance with the License. You may obtain a copy of the License at
 * http://opensource.org/licenses/MIT
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.strongback;

import java.util.concurrent.CountDownLatch;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.atomic.AtomicLong;
import java.util.function.Consumer;

import org.strongback.Executor.Priority;
import org.strongback.Strongback.Configurator;
import org.strongback.annotation.ThreadSafe;

import com.codahale.metrics.Histogram;
import com.codahale.metrics.Snapshot;
import com.codahale.metrics.UniformReservoir;

/**
 * A command that measures the {@link Strongback.Configurator#useExecutionPeriod(long, java.util.concurrent.TimeUnit) execution
 * rate} of the Strongback {@link Executor}. This is purely for test purposes.
 * <p>
 *
 * @author Randall Hauch
 */
@ThreadSafe
public final class ExecutableTimer implements Executable {

 /**
 * Measure the timing of the {@link Executor} and print the histogram of timing results to {@link System#out}. The resulting
 * timer will be {@link Executor#register(Executable) registered} with the Executor, and upon completion will automatically
 * unregister itself.
 * <p>
 * This method can be used to print a histogram of {@link Strongback#executor() Strongback's executor}. The following
 * example uses 1000 samples, which corresponds to 5 seconds if the {@link Configurator#useExecutionPeriod(long, TimeUnit)
 * execution rate} is 5 milliseconds:
 *
 * <pre>
 * ExecutableTimer.measureTimingAndPrint(Strongback.executor(), 200 * 5);
 * </pre>
 *
 * The result would be something like the following:
 *
 * @param executor the Executor to measure; may not be null
 * @param desc the description
 * @param numberOfSamples the number of samples to measure
 * @return the executable timer
 */
 public static ExecutableTimer measureTimingAndPrint(Executor executor, String desc, int numberOfSamples) {
 return measureTiming(executor, numberOfSamples, snapshot -> {
 System.out.println("Execution timing statistics" + (desc != null ? " (" + desc + ")" : ""));
 System.out.println(" Size of histogram: " + snapshot.getValues().length);
 System.out.println(" Minimum (ms): " + snapshot.getMin());
 System.out.println(" Maximum (ms): " + snapshot.getMax());
 System.out.println(" Mean (ms): " + snapshot.getMean());
 System.out.println(" Median (ms): " + snapshot.getMedian());
 System.out.println(" Standard dev (ms): " + snapshot.getStdDev());
 System.out.println(" 75th percentile (ms): " + snapshot.get75thPercentile());
 System.out.println(" 95th percentile (ms): " + snapshot.get95thPercentile());
 System.out.println(" 98th percentile (ms): " + snapshot.get98thPercentile());
 System.out.println(" 99th percentile (ms): " + snapshot.get99thPercentile());
 System.out.println(" 99.9th percentile (ms): " + snapshot.get999thPercentile());
 //snapshot.dump(System.out);
 });
 }

 public static ExecutableTimer measureTiming(Executor executor, int numberOfSamples, Consumer<Snapshot> atCompletion) {
 ExecutableTimer timer = new ExecutableTimer(numberOfSamples, (theTimer) -> {
 executor.unregister(theTimer);
 if (atCompletion != null) atCompletion.accept(theTimer.getResults());
 });
 // Register the timer with the executor ...
 executor.register(timer, Priority.HIGH);
 return timer;
 }

 private final CountDownLatch latch = new CountDownLatch(1);
 private final Consumer<ExecutableTimer> resultsHandler;
 private final Histogram histogram;
 private final int numSamples;
 private final AtomicLong lastStartTime = new AtomicLong();
 private final AtomicLong count = new AtomicLong(-1);

 /**
 * Create an executable timer that measures the specified number of samples.
 *
 * @param numberOfSamples the maximum number of samples to take; must be positive
 * @param uponCompletion the function that will be called
 */
 private ExecutableTimer(int numberOfSamples, Consumer<ExecutableTimer> uponCompletion) {
 histogram = new Histogram(new UniformReservoir(numberOfSamples));
 numSamples = numberOfSamples;
 resultsHandler = uponCompletion;
 }

 @Override
 public void execute(long timeInMillis) {
 long currentCount = count.getAndIncrement();
 if (currentCount < 0) {
 lastStartTime.set(timeInMillis);
 } else if (currentCount < numSamples) {
 histogram.update(timeInMillis - lastStartTime.getAndSet(timeInMillis));
 } else {
 count.set(-1);
 // We've completed, so first run the results handler and only then release the latch ...
 resultsHandler.accept(this);
 latch.countDown();
 }
 }

 public boolean isComplete() {
 return latch.getCount() == -1 && histogram.getCount() > 0;
 }

 public ExecutableTimer await(long timeout, TimeUnit unit) throws InterruptedException {
 latch.await(timeout, unit);
 return this;
 }

 public ExecutableTimer await() throws InterruptedException {
 latch.await();
 return this;
 }

 public Snapshot getResults() {
 return histogram.getSnapshot();
 }
}