Stopwatch
Date: 2016-05-24

com.google.common.base

## Class Stopwatch

- java.lang.Object
- - com.google.common.base.Stopwatch

-     @GwtCompatible(emulated=true)
      public final class Stopwatch
      extends java.lang.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

         long millis = stopwatch.elapsed(MILLISECONDS);

         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.

  Since:
    10.0

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static Stopwatch` | `createStarted()` Creates (and starts) a new stopwatch using `System.nanoTime()` as its time source.
    `static Stopwatch` | `createStarted(Ticker ticker)` Creates (and starts) a new stopwatch, using the specified time source.
    `static Stopwatch` | `createUnstarted()` Creates (but does not start) a new stopwatch using `System.nanoTime()` as its time source.
    `static Stopwatch` | `createUnstarted(Ticker ticker)` Creates (but does not start) a new stopwatch, using the specified time source.
    `long` | `elapsed(java.util.concurrent.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()`.
    `Stopwatch` | `reset()` Sets the elapsed time for this stopwatch to zero, and places it in a stopped state.
    `Stopwatch` | `start()` Starts the stopwatch.
    `Stopwatch` | `stop()` Stops the stopwatch.
    `java.lang.String` | `toString()` Returns a string representation of the current elapsed time.

    - ### Methods inherited from class java.lang.Object

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

- - ### Method Detail

    - #### createUnstarted

          @CheckReturnValue
          public static Stopwatch createUnstarted()

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

    - #### createUnstarted

          @CheckReturnValue
          public static Stopwatch createUnstarted(Ticker ticker)

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

    - #### createStarted

          @CheckReturnValue
          public static Stopwatch createStarted()

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

    - #### createStarted

          @CheckReturnValue
          public static Stopwatch createStarted(Ticker ticker)

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

    - #### isRunning

          @CheckReturnValue
          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:
        `java.lang.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:
        `java.lang.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

          @CheckReturnValue
          public long elapsed(java.util.concurrent.TimeUnit desiredUnit)

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

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

      Since:
        14.0 (since 10.0 as `elapsedTime()`)

    - #### toString

          @GwtIncompatible(value="String.format()")
          public java.lang.String toString()

      Returns a string representation of the current elapsed time.
      Overrides:
        `toString` in class `java.lang.Object`