com.fillumina.performance.package-info 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!
/**
 * This API helps to perform benchmarks on your code.
 * 
 * To asses performances of a java code can be tough.
 * First Java runs on a variety of
 * platforms (from mobiles to mainframes) and it's difficult to
 * tell how some code will perform in all of them (think about memory
 * or FPU constrains).
 * Then the JVM itself is not unique (there are many producers)
 * and may threat the byte-code at execution time in different ways.
 * Other than that most of the environments it runs on use
 * multitasking to perform various operations simultaneously and even
 * the Java garbage collector may impact the performance results unpredictably.
 * For these reasons a test must run for a considerable number of iterations
 * so to average all these disturbances and possibly eliminate them.
 * 

 * Evaluating how long a (relatively small) code takes to execute is a kind
 * of performance test called micro-benchmark as opposed to the
 * classic benchmarks which usually concern full program execution.
 * A micro-benchmark has the disadvantage of making it difficult to compare
 * measures obtained from different systems.
 * 

 * Another approach is to take the measurements of two or more different codes
 * and consider the relative speed.
 * This would allow some advantages over a micro-benchmark:
 * 

 * The framework overhead is eliminated (all codes under test
 * are subjects to the same overhead);
 * 
Percentages are more reproducible and constant between different systems;
 * 
It's far more informative to know how much a code is faster in
 * respect of another known code than how much time it takes on a certain system;
 * 
It's more robust against environment disturbances (CPU-time fluctuations).
 * 
 *
 * This is the approach chosen by this API although nothing forbids
 * to specify only one test (so having a micro-benchmark).
 * 
 * It has the following features:
 * 

 * It allows to test code in a single threaded and in
 * multi threaded environment;
 * 
It allows to specify parametrized codes
 * (same test used with different inputs);
 * 
It allows to use a sequence as a second parameter of a parametrized
 * codes (same test, different inputs each with a sequence of secondary inputs);
 * 
It allows to easily export the performances or use them on place
 * (actually human readable prints out and CSV are present but the
 * mechanism is very easy to extend to whatever purpose, even reading the
 * performances in real-time to update a GUI);
 * 
It allows to assert conditions about the codes so to use
 * them in unit tests;
 * 
The structure of the API is very open and interface centric
 * so that it is highly customizable and expandable;
 * 
It can be used with two different paradigms: fluent interface and
 * templates which assures, respectively, maximum flexibility and
 * easiness of use.
 * 
 *
 * @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
 */
package com.fillumina.performance;