Module de.cuioss.java.tools
Package de.cuioss.tools.concurrent

Class StopWatch

java.lang.Object
de.cuioss.tools.concurrent.StopWatch
All Implemented Interfaces:
Serializable
public final class StopWatch extends Object implements Serializable
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(Ticker) or createStarted(Ticker) 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.

Author:
com.google.common.base.Stopwatch
See Also:

  • Method Details

    • createUnstarted

      public static StopWatch createUnstarted()
      Returns:
      a created (but not started) new stopwatch using System.nanoTime() as its time source.

    • createUnstarted

      public static StopWatch createUnstarted(Ticker ticker)
      Parameters:
      ticker - specified time source, must not be null
      Returns:
      a created (but not started) new stopwatch, using the specified time source.

    • createStarted

      public static StopWatch createStarted()
      Returns:
      a created (and started) new stopwatch using System.nanoTime() as its time source.

    • createStarted

      public static StopWatch createStarted(Ticker ticker)
      Parameters:
      ticker - specified time source, must not be null
      Returns:
      a created (and started) new stopwatch, using the specified time source.

    • 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 StopWatch start()
      Starts the stopwatch.
      Returns:
      this StopWatch instance
      Throws:
      IllegalStateException - if the stopwatch is already running.

    • stop

      public StopWatch 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 StopWatch 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)
      Parameters:
      desiredUnit - must not be null
      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.

    • toString

      public String toString()
      Returns a string representation of the current elapsed time.
      Overrides:
      toString in class Object