org.apache.ignite.internal.util

Class IgniteStopwatch

java.lang.Object

org.apache.ignite.internal.util.IgniteStopwatch

public final class IgniteStopwatch
extends Object

An object that measures elapsed time in nanoseconds. It is useful to measure elapsed time using this class instead of direct calls to System.nanoTime() for a few reasons:

• An alternate time source can be substituted, for testing or performance reasons.
• As documented by nanoTime, the value returned has no absolute meaning, and can only be interpreted as relative to another timestamp returned by nanoTime at a different time. Stopwatch is a more effective abstraction because it exposes only these relative values, not the absolute ones.

Basic usage:

 Stopwatch stopwatch = Stopwatch.createStarted();
 doSomething();
 stopwatch.stop(); // optional

 Duration duration = stopwatch.elapsed();

 log.info("time: " + stopwatch); // formatted string like "12.3 ms"
 

Stopwatch methods are not idempotent; it is an error to start or stop a stopwatch that is already in the desired state.

When testing code that uses this class, use createUnstarted(IgniteTicker) or createStarted(IgniteTicker) to supply a fake or mock ticker. This allows you to simulate any valid behavior of the stopwatch.

Note: This class is not thread-safe.

Warning for Android users: a stopwatch with default behavior may not continue to keep time while the device is asleep. Instead, create one like this:

 Stopwatch.createStarted(
      new Ticker() {
        public long read() {
          return android.os.SystemClock.elapsedRealtimeNanos();
        }
      });
 

Method Summary

Modifier and Type	Method and Description
static IgniteStopwatch	createStarted() Creates (and starts) a new stopwatch using System.nanoTime() as its time source.
static IgniteStopwatch	createStarted(IgniteTicker ticker) Creates (and starts) a new stopwatch, using the specified time source.
static IgniteStopwatch	createUnstarted() Creates (but does not start) a new stopwatch using System.nanoTime() as its time source.
static IgniteStopwatch	createUnstarted(IgniteTicker ticker) Creates (but does not start) a new stopwatch, using the specified time source.
Duration	elapsed() Returns the current elapsed time shown on this stopwatch as a Duration.
long	elapsed(TimeUnit desiredUnit) Returns the current elapsed time shown on this stopwatch, expressed in the desired time unit, with any fraction rounded down.
boolean	isRunning() Returns true if start() has been called on this stopwatch, and stop() has not been called since the last call to start().
static void	logTime(IgniteLogger log, String operationName, IgniteThrowableRunner operation) Execution given operation and calculation it time.
IgniteStopwatch	reset() Sets the elapsed time for this stopwatch to zero, and places it in a stopped state.
IgniteStopwatch	start() Starts the stopwatch.
IgniteStopwatch	stop() Stops the stopwatch.

Methods inherited from class java.lang.Object

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

Method Detail

createUnstarted

public static IgniteStopwatch createUnstarted()

Creates (but does not start) a new stopwatch using System.nanoTime() as its time source.

createUnstarted

public static IgniteStopwatch createUnstarted(IgniteTicker ticker)

Creates (but does not start) a new stopwatch, using the specified time source.

createStarted

public static IgniteStopwatch createStarted()

Creates (and starts) a new stopwatch using System.nanoTime() as its time source.

createStarted

public static IgniteStopwatch createStarted(IgniteTicker ticker)

Creates (and starts) a new stopwatch, using the specified time source.

logTime

public static void logTime(IgniteLogger log,
                           String operationName,
                           IgniteThrowableRunner operation)
                    throws IgniteCheckedException

Execution given operation and calculation it time.

Parameters:

log - Logger fol logging.

operationName - Operation name for logging.

operation - Operation for execution.

Throws:

IgniteCheckedException - If failed.

isRunning

public boolean isRunning()

Returns true if start() has been called on this stopwatch, and stop() has not been called since the last call to start().

start

public IgniteStopwatch start()

Starts the stopwatch.

Returns:

this Stopwatch instance

Throws:

IllegalStateException - if the stopwatch is already running.

stop

public IgniteStopwatch stop()

Stops the stopwatch. Future reads will return the fixed duration that had elapsed up to this point.

Returns:

this Stopwatch instance

Throws:

IllegalStateException - if the stopwatch is already stopped.

reset

public IgniteStopwatch reset()

Sets the elapsed time for this stopwatch to zero, and places it in a stopped state.

Returns:

this Stopwatch instance

elapsed

public long elapsed(TimeUnit desiredUnit)

Returns the current elapsed time shown on this stopwatch, expressed in the desired time unit, with any fraction rounded down.

Note: the overhead of measurement can be more than a microsecond, so it is generally not useful to specify TimeUnit.NANOSECONDS precision here.

It is generally not a good idea to use an ambiguous, unitless long to represent elapsed time. Therefore, we recommend using elapsed() instead, which returns a strongly-typed Duration instance.

elapsed

public Duration elapsed()

Returns the current elapsed time shown on this stopwatch as a Duration. Unlike elapsed(TimeUnit), this method does not lose any precision due to rounding.