org.dishevelled.timer
Class Timer

java.lang.Object
  org.dishevelled.timer.Timer

public final class Timer
extends Object

Timer class with nanosecond resolution and summary statistics on recorded elapsed times. This class provides nanosecond precision but not necessarily nanosecond accuracy (see the javadoc for System.nanoTime() for more details). The recorded times themselves are not preserved, however, only the statistics. As a consequence start() and stop() can be called many number of times without requiring large amounts of memory.

Special cases

When size() == 0,

 min() == Double.NaN
 max() == Double.NaN
 mean() == Double.NaN
 standardDeviation() == Double.NaN
 

When size() == 1,

 standardDeviation() == 0.0d
 

Static methods

Execution time can be sensitive to various factors, such as order of execution, runtime optimization from the just-in-time compiler (JIT), and garbage collection. This class provides static methods to help deal with these factors.

Given a few benchmarks to run, wrap them in Runnable objects

 Runnable r0 = new Runnable() { public void run() { ... } };
 Runnable r1 = new Runnable() { public void run() { ... } };
 Runnable r2 = new Runnable() { public void run() { ... } };
 List<Runnable> benchmarks = Arrays.asList(new Runnable[] { r0, r1, r2 });
 

Prime the JIT by running the benchmarks several times

 Timer.prime(benchmarks, 1000);
 

Then measure the execution times of the benchmarks by running them several times in random execution order

 Map<Runnable, Timer> result = Timer.shuffle(benchmarks, 100, 100);
 

Summary statistics on recorded execution times are captured by the timer returned for each Runnable benchmark

 for (Map.Entry<Runnable, Timer> e : result.entrySet()) {
   Runnable r = e.getKey();
   Timer t = e.getValue();
   System.out.println("runnable=" + r + " mean execution time=" + t.mean() + "ns");
 }
 

Version:

$Revision: 976 $ $Date: 2011-01-04 21:46:30 -0600 (Tue, 04 Jan 2011) $

Author:

Michael Heuer

See Also:

System.nanoTime()

Constructor Summary

Timer()
Create a new timer.

Method Summary

static Map<Runnable,Timer>	loop(List<? extends Runnable> codeBlocks, int n) For each of the code blocks in the specified list of code blocks, loop over the code block n times.
static Map<Runnable,Timer>	loop(List<? extends Runnable> codeBlocks, int n, int m) Loop over the code blocks in the specified list of code blocks n times, executing each code block m times.
static Timer	loop(Runnable codeBlock, int n) Loop over the specified code block n times.
static Timer	loop(Runnable codeBlock, int n, Timer t) Loop over the specified code block n times with the specified timer.
double	max() Return the maximum elapsed time recorded by this timer in nanoseconds.
double	mean() Return the arithmetic mean of the elapsed times recorded by this timer in nanoseconds.
double	min() Return the minimum elapsed time recorded by this timer in nanoseconds.
static void	prime(List<? extends Runnable> codeBlocks, int n) Prime the just-in-time compiler (JIT) by executing each code block in the specified list of code blocks n times.
static void	prime(Runnable codeBlock, int n) Prime the just-in-time compiler (JIT) by executing the specified code block n times.
void	reset() Reset the record of elapsed times from this timer.
static Map<Runnable,Timer>	shuffle(List<? extends Runnable> codeBlocks, int n) For each of the code blocks in the specified list of code blocks, executed in random order, loop over the code block n times.
static Map<Runnable,Timer>	shuffle(List<? extends Runnable> codeBlocks, int n, int m) Loop over the code blocks in the specified list of code blocks n times, in random order, executing each code block m times.
static Map<Runnable,Timer>	shuffle(List<? extends Runnable> codeBlocks, int n, int m, Random random) Loop over the code blocks in the specified list of code blocks n times, in random order using the specified source of randomness, executing each code block m times.
static Map<Runnable,Timer>	shuffle(List<? extends Runnable> codeBlocks, int n, Random random) For each of the code blocks in the specified list of code blocks, executed in random order using the specified source of randomness, loop over the code block n times.
long	size() Return the number of elapsed times recorded by this timer.
double	standardDeviation() Return the standard deviation of the elapsed times recorded by this timer in nanoseconds.
void	start() Start the timer.
void	stop() Stop the timer and record the time elapsed in nanoseconds since start() was last called.
double	sum() Return the sum of the elapsed times recorded by this timer in nanoseconds.
static Timer	time(Runnable codeBlock) Time the specified code block.
static Timer	time(Runnable codeBlock, Timer t) Time the specified code block with the specified timer.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Timer

public Timer()

Create a new timer.

Method Detail

reset

public void reset()

Reset the record of elapsed times from this timer. After the timer has been reset, it must be started at least once before stop() is called.

start

public void start()

Start the timer. The timer must be started at least once before stop() is called.

stop

public void stop()

Stop the timer and record the time elapsed in nanoseconds since start() was last called.

Throws:

TimerException - if start() has not been called at least once before this method was called

min

public double min()

Return the minimum elapsed time recorded by this timer in nanoseconds.

Returns:

the minimum elapsed time recorded by this timer in nanoseconds

max

public double max()

Return the maximum elapsed time recorded by this timer in nanoseconds.

Returns:

the maximum elapsed time recorded by this timer in nanoseconds

size

public long size()

Return the number of elapsed times recorded by this timer.

Returns:

the number of elapsed times recorded by this timer

sum

public double sum()

Return the sum of the elapsed times recorded by this timer in nanoseconds.

Returns:

the sum of the elapsed times recorded by this timer

mean

public double mean()

Return the arithmetic mean of the elapsed times recorded by this timer in nanoseconds.

Returns:

the arithmetic mean of the elapsed times recorded by this timer in nanoseconds

standardDeviation

public double standardDeviation()

Return the standard deviation of the elapsed times recorded by this timer in nanoseconds.

Returns:

the standard deviation of the elapsed times recorded by this timer in nanoseconds

time

public static Timer time(Runnable codeBlock)

Time the specified code block.

Parameters:

codeBlock - code block to execute

Returns:

timer used to measure execution time

time

public static Timer time(Runnable codeBlock,
                         Timer t)

Time the specified code block with the specified timer.

Parameters:

codeBlock - code block to execute

t - timer to use to measure execution time

Returns:

timer used to measure execution time

prime

public static void prime(Runnable codeBlock,
                         int n)

Prime the just-in-time compiler (JIT) by executing the specified code block n times.

Parameters:

codeBlock - code block to execute

n - number of times to execute code block

prime

public static void prime(List<? extends Runnable> codeBlocks,
                         int n)

Prime the just-in-time compiler (JIT) by executing each code block in the specified list of code blocks n times.

Parameters:

codeBlocks - list of code blocks to execute

n - number of times to execute each code block

loop

public static Timer loop(Runnable codeBlock,
                         int n)

Loop over the specified code block n times.

Parameters:

codeBlock - code block to execute

n - number of times to execute code block

Returns:

timer used to measure execution time

loop

public static Timer loop(Runnable codeBlock,
                         int n,
                         Timer t)

Loop over the specified code block n times with the specified timer.

Parameters:

codeBlock - code block to execute

n - number of times to execute code block

t - timer to use to measure execution time

Returns:

timer used to measure execution time

loop

public static Map<Runnable,Timer> loop(List<? extends Runnable> codeBlocks,
                                       int n)

For each of the code blocks in the specified list of code blocks, loop over the code block n times.

Parameters:

codeBlocks - list of code blocks to execute

n - number of times to execute each code block

Returns:

map of code blocks to timers used to measure execution time

loop

public static Map<Runnable,Timer> loop(List<? extends Runnable> codeBlocks,
                                       int n,
                                       int m)

Loop over the code blocks in the specified list of code blocks n times, executing each code block m times.

Parameters:

codeBlocks - list of code blocks to execute

n - number of times to loop over the list of code blocks

m - number of times to execute each code block

Returns:

map of code blocks to timers used to measure execution time

shuffle

public static Map<Runnable,Timer> shuffle(List<? extends Runnable> codeBlocks,
                                          int n)

For each of the code blocks in the specified list of code blocks, executed in random order, loop over the code block n times.

Parameters:

codeBlocks - list of code blocks to execute

n - number of times to execute each code block

Returns:

map of code blocks to timers used to measure execution time

shuffle

public static Map<Runnable,Timer> shuffle(List<? extends Runnable> codeBlocks,
                                          int n,
                                          Random random)

For each of the code blocks in the specified list of code blocks, executed in random order using the specified source of randomness, loop over the code block n times.

Parameters:

codeBlocks - list of code blocks to execute

n - number of times to execute each code block

random - source of randomness

Returns:

map of code blocks to timers used to measure execution time

shuffle

public static Map<Runnable,Timer> shuffle(List<? extends Runnable> codeBlocks,
                                          int n,
                                          int m)

Loop over the code blocks in the specified list of code blocks n times, in random order, executing each code block m times.

Parameters:

codeBlocks - list of code blocks to execute

n - number of times to loop over the list of code blocks

m - number of times to execute each code block

Returns:

map of code blocks to timers used to measure execution time

shuffle

public static Map<Runnable,Timer> shuffle(List<? extends Runnable> codeBlocks,
                                          int n,
                                          int m,
                                          Random random)

Loop over the code blocks in the specified list of code blocks n times, in random order using the specified source of randomness, executing each code block m times.

Parameters:

codeBlocks - list of code blocks to execute

n - number of times to loop over the list of code blocks

m - number of times to execute each code block

random - source of randomness

Returns:

map of code blocks to timers used to measure execution time