org.javasimon
Interface Stopwatch

All Superinterfaces:

HasAttributes, Simon

All Known Implementing Classes:

NullStopwatch, StopwatchImpl

public interface Stopwatch
extends Simon

Stopwatch Simon measures time spans and holds related statistics. Methods start() creates new Split object. On this object you can call Split.stop() - this demarcates measured interval. Alternatively method addTime(long) can be used to add split time to the stopwatch. Both ways effectively updates usage times, increase usage counter by one and updates total time of the stopwatch. Split object enables multiple time-splits to be measured in parallel.

Example:

 Split split = SimonManager.getStopwatch("com.my.stopwatch").start();
 //... here goes the measured code
 split.stop();
 System.out.println("Result: " + split.getStopwatch()); // print will be probably somewhere else

This can be used for simple micro-benchmarking, critical section monitoring, in web filter to measure request times, etc. SimonManager should always be used to get the stopwatch before using it, because otherwise the code will not reflect enable/disable of the whole API.

Disable/enable considerations

While Counter's usage is atomic, Stopwatch measures splits and every measurement involves two calls (start/stop) over a period of time. It's important to know how various management actions affect measurement:

• If start OR stop is called with disabled Simon, nothing is measured. That means that if stopwatch is disabled or enabled between these calls, stop always returns 0 and totals are not updated.
• If stopwatch is obtained from enabled Manager (API is enabled) and Manager is later disabled before stop, this split is measured because real stopwatch instance was obtained (considering that the Stopwatch itself is enabled). If it's other way around then the split is not measured because obtained instance is "null" Simon.

While API disable causes that the code works with "null" Simons, state of the real Simon is perfectly preserved. Disabling particular Simon on the other hand resets some of its state. When the stopwatch is disabled, its active count is set to 0 and before it is enabled again both its thread-local split map and keyed-object split map is cleared. Of course, all totals/counts are preserved.

Other usages

Reset of the stopwatch resets all stats except usages that are rather management related and should not be reset. Reset is used often for various sampling purposes which requires that only cumulative stats are reset, but all running splits are preserved. Running splits will be added to the stopwatch after reset when respective stop methods are called.

Author:

Richard "Virgo" Richter

Method Summary

Stopwatch	addSplit(Split split) Adds Split to the stopwatch which is useful for aggregation of splits created for other stopwatch.
Stopwatch	addTime(long ns) Adds split time in nanoseconds to total time of the stopwatch.
long	getActive() Returns current number of measured splits (concurrently running).
long	getCounter() Returns usage count of the stopwatch.
long	getLast() Returns value of the last added split - wheter it was added directly or with stop method.
long	getMax() Returns maximal time split value in nanoseconds.
long	getMaxActive() Returns peek value of active concurrent splits.
long	getMaxActiveTimestamp() Retruns ms timestamp when the last peek of the active split count occured.
long	getMaxTimestamp() Returns ms timestamp when the max value was measured.
double	getMean() Returns mean value (average) of all measured values.
long	getMin() Returns minimal time split value in nanoseconds.
long	getMinTimestamp() Returns ms timestamp when the min value was measured.
double	getStandardDeviation() Returns standard deviation for all measured values.
long	getTotal() Returns total sum of all split times in nanoseconds.
double	getVariance() Returns unbiased estimate of the population variance.
double	getVarianceN() Returns variance value of all measured values (entire population).
Stopwatch	reset() Resets the Simon - clears total time, min, max, usage stats, etc.
StopwatchSample	sample() Samples Simon values and returns them in a Java Bean derived from Sample interface.
StopwatchSample	sampleAndReset() Samples Simon values and returns them in a Java Bean derived from Sample interface and resets the Simon.
Split	start() Starts the new split for this stopwatch.

Methods inherited from interface org.javasimon.Simon

getFirstUsage, getChildren, getLastReset, getLastUsage, getName, getNote, getParent, getState, isEnabled, setNote, setState

Methods inherited from interface org.javasimon.HasAttributes

getAttribute, getAttribute, getAttributeNames, getCopyAsSortedMap, removeAttribute, setAttribute

Method Detail

start

Split start()

Starts the new split for this stopwatch. This action does not hold any resources and if Split object is collected, no leak occurs. However, active count is increased and without stopping the split active count stays increased which may render that information useless.

Returns:

split object

See Also:

Split.stop()

addTime

Stopwatch addTime(long ns)

Adds split time in nanoseconds to total time of the stopwatch.

Parameters:

ns - split time

Returns:

this stopwatch

addSplit

Stopwatch addSplit(Split split)

Adds Split to the stopwatch which is useful for aggregation of splits created for other stopwatch. Split object should be stopped. Main difference is the callback method called as Callback.onStopwatchAdd(Stopwatch, Split, StopwatchSample) provides split object to the callback.

Usage examples:

Split split = Split.start(); // no stopwatch needed
...
someStopwatch.addSplit(split.stop()); // you may omit stop(), if you does not use the split after this point

Parameters:

split - split object (should be stopped)

Returns:

this stopwatch

Since:

3.1

getTotal

long getTotal()

Returns total sum of all split times in nanoseconds.

Returns:

total time of the stopwatch in nanoseconds

getLast

long getLast()

Returns value of the last added split - wheter it was added directly or with stop method.

Returns:

value of the last added split

getCounter

long getCounter()

Returns usage count of the stopwatch. Counter is increased by addTime and stop - that means that it's updated every time the next time split is added.

Returns:

count of time splits

getMax

long getMax()

Returns maximal time split value in nanoseconds.

Returns:

maximal time split in nanoseconds

getMin

long getMin()

Returns minimal time split value in nanoseconds.

Returns:

minimal time split in nanoseconds

getMaxTimestamp

long getMaxTimestamp()

Returns ms timestamp when the max value was measured.

Returns:

ms timestamp of the max value measurement

getMinTimestamp

long getMinTimestamp()

Returns ms timestamp when the min value was measured.

Returns:

ms timestamp of the min value measurement

reset

Stopwatch reset()

Resets the Simon - clears total time, min, max, usage stats, etc. Split times that started before reset will be counted when appropriate stop is called, so no split time is ignored by the stopwatch. Active count is not reset.

Specified by:

reset in interface Simon

Returns:

returns this

getActive

long getActive()

Returns current number of measured splits (concurrently running). This counter can show more splits than is measured at any moment if some splits were "forgotten" (not stopped and garbage collected). This does not imply any resource leak, just bad practice of not stopping Splits somewhere in the client code.

Returns:

current number of active splits

getMaxActive

long getMaxActive()

Returns peek value of active concurrent splits.

Returns:

maximum reached value of active splits

getMaxActiveTimestamp

long getMaxActiveTimestamp()

Retruns ms timestamp when the last peek of the active split count occured.

Returns:

ms timestamp of the last peek of the active split count

getMean

double getMean()

Returns mean value (average) of all measured values.

Returns:

mean value

getStandardDeviation

double getStandardDeviation()

Returns standard deviation for all measured values.

Returns:

standard deviation

getVariance

double getVariance()

Returns unbiased estimate of the population variance.

Returns:

unbiased estimated variance

getVarianceN

double getVarianceN()

Returns variance value of all measured values (entire population).

Returns:

entire population variance

sample

StopwatchSample sample()

Description copied from interface: Simon

Samples Simon values and returns them in a Java Bean derived from Sample interface.

Specified by:

sample in interface Simon

Returns:

sample containing all Simon values

sampleAndReset

StopwatchSample sampleAndReset()

Description copied from interface: Simon

Samples Simon values and returns them in a Java Bean derived from Sample interface and resets the Simon. Operation is synchronized to assure atomicity.

Specified by:

sampleAndReset in interface Simon

Returns:

sample containing all Simon values