com.fillumina.performance.producer.InstrumentablePerformanceExecutor Maven / Gradle / Ivy

Go to download

Show more of this group Show more artifacts with this name
Show all versions of performance-tools Show documentation

Configurable tool to easily compare performances of different code snippets and to take performance telemetry of a running application.

The newest version!

package com.fillumina.performance.producer;

/**
 * Defines an executor able to contains tests ({@link TestContainer})
 * and execute them producing performances as a result ({@link LoopPerformances})
 * that will be passed to
 * {@link com.fillumina.performance.consumer.PerformanceConsumer}s.
 * This executor is also instrumentable so that it can be passed to a
 * {@link PerformanceExecutorInstrumenter} that can execute it.
 *
 * @see 
 *      Java theory and practice: Anatomy of a flawed microbenchmark
 *      (Brian Goetz)
 *      
 *
 * @see 
 *      Java theory and practice: Dynamic compilation and performance measurement
 *      (Brian Goetz)
 *      
 *
 * @author Francesco Illuminati
 */
public interface InstrumentablePerformanceExecutor
        >
        extends PerformanceProducer, TestContainer {

    /**
     * Allows the executor to be piloted by another given class.
     * It may be used by instrumenters that modify the behavior of the
     * instrumentable
     * (like {@link com.fillumina.performance.producer.progression.AutoProgressionPerformanceInstrumenter})
     * or by classes that uses the instrumentable to execute
     * their own tests (like
     * {@link com.fillumina.performance.producer.suite.ParametrizedPerformanceSuite}
     * or
     * {@link com.fillumina.performance.producer.suite.ParametrizedSequencePerformanceSuite}).
     * 
     * IMPORTANT: the returned object is the one passed as an argument so
     * in a 
     * fluent interface the next method refers to the argument:
     * 
     *      first.instrumentedBy(second)
     *          .secondMethod();
     * 
     * Is the same as:
     *      *      first.instrumentedBy(second);
     *      second.secondMethod();
     * 
     *
     * @see com.fillumina.performance.producer.progression.ProgressionPerformanceInstrumenter
     * @see com.fillumina.performance.producer.progression.AutoProgressionPerformanceInstrumenter
     * @see com.fillumina.performance.producer.suite.ParametrizedPerformanceSuite
     * @see com.fillumina.performance.producer.suite.ParametrizedSequencePerformanceSuite
     */
     T
            instrumentedBy(final T instrumenter);

    /**
     * Executes the tests.
     */
    LoopPerformancesHolder execute();

    /**
     * Executes the test without extracting statistics. It is useful
     * to force the JVM to perform early code optimizations before the actual
     * performance measurements are taken. You should run a particular code
     * at least some thousand times (depending on the JVM) for optimizations
     * to kick off.
     *
     * @see 
     *      Java theory and practice: Dynamic compilation and performance measurement
     *      (Brian Goetz)
     *      
     */
    InstrumentablePerformanceExecutor warmup();
}