Class Stopwatch


  • @GwtCompatible(emulated=true)
    public final class Stopwatch
    extends java.lang.Object
    An object that accurately measures elapsed time: the measured duration between two successive readings of "now" in the same process.

    In contrast, wall time is a reading of "now" as given by a method like System.currentTimeMillis(), best represented as an Instant. Such values can be subtracted to obtain a Duration (such as by Duration.between), but doing so does not give a reliable measurement of elapsed time, because wall time readings are inherently approximate, routinely affected by periodic clock corrections. Because this class (by default) uses System.nanoTime(), it is unaffected by these changes.

    Use this class instead of direct calls to System.nanoTime() for two reasons:

    • The raw long values returned by nanoTime are meaningless and unsafe to use in any other way than how Stopwatch uses them.
    • An alternative source of nanosecond ticks can be substituted, for example for testing or performance reasons, without affecting most of your code.

    Basic usage:

    
     Stopwatch stopwatch = Stopwatch.createStarted();
     doSomething();
     stopwatch.stop(); // optional
    
     Duration duration = stopwatch.elapsed();
    
     log.info("time: " + stopwatch); // formatted string like "12.3 ms"
     

    The state-changing 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.

    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();
            }
          });
     
    Since:
    10.0
    Author:
    Kevin Bourrillion
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method 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.
      java.time.Duration elapsed()
      Returns the current elapsed time shown on this stopwatch as a Duration.
      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.
      long elapsedMillis()
      Deprecated.
      Use stopwatch.elapsed(MILLISECONDS) instead.
      long elapsedTime​(java.util.concurrent.TimeUnit desiredUnit)
      Deprecated.
      Use elapsed(TimeUnit) instead.
      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.
      java.lang.String toString​(int significantDigits)
      Deprecated.
      Use toString() instead.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
    • Method Detail

      • createUnstarted

        public static Stopwatch createUnstarted()
        Creates (but does not start) a new stopwatch using System.nanoTime() as its time source.
        Since:
        15.0
      • createUnstarted

        public static Stopwatch createUnstarted​(Ticker ticker)
        Creates (but does not start) a new stopwatch, using the specified time source.
        Since:
        15.0
      • createStarted

        public static Stopwatch createStarted()
        Creates (and starts) a new stopwatch using System.nanoTime() as its time source.
        Since:
        15.0
      • createStarted

        public static Stopwatch createStarted​(Ticker ticker)
        Creates (and starts) a new stopwatch, using the specified time source.
        Since:
        15.0
      • 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

        @CanIgnoreReturnValue
        public Stopwatch start()
        Starts the stopwatch.
        Returns:
        this Stopwatch instance
        Throws:
        java.lang.IllegalStateException - if the stopwatch is already running.
      • stop

        @CanIgnoreReturnValue
        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.
      • elapsed

        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: 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.

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

        @Deprecated
        public long elapsedTime​(java.util.concurrent.TimeUnit desiredUnit)
        Deprecated.
        Use elapsed(TimeUnit) instead. This method is scheduled to be removed in Guava release 16.0.
        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.

      • elapsedMillis

        @Deprecated
        public long elapsedMillis()
        Deprecated.
        Use stopwatch.elapsed(MILLISECONDS) instead. This method is scheduled to be removed in Guava release 16.0.
        Returns the current elapsed time shown on this stopwatch, expressed in milliseconds, with any fraction rounded down. This is identical to elapsed(TimeUnit.MILLISECONDS).
      • toString

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

        @Deprecated
        public java.lang.String toString​(int significantDigits)
        Deprecated.
        Use toString() instead. This method is scheduled to be removed in Guava release 15.0.
        Returns a string representation of the current elapsed time, choosing an appropriate unit and using the specified number of significant figures. For example, at the instant when elapsed(NANOSECONDS) would return {1234567}, toString(4) returns "1.235 ms".