Class Stopwatch
- java.lang.Object
-
- com.google.common.base.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 anInstant
. Such values can be subtracted to obtain aDuration
(such as byDuration.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) usesSystem.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 bynanoTime
are meaningless and unsafe to use in any other way than howStopwatch
uses them. - An alternative source of nanosecond ticks can be substituted, for example for testing or performance reasons, without affecting most of your code.
The one downside of
Stopwatch
relative toSystem.nanoTime()
is thatStopwatch
requires object allocation and additional method calls, which can reduce the accuracy of the elapsed times reported.Stopwatch
is still suitable for logging and metrics where reasonably accurate values are sufficient. If the uncommon case that you need to maximize accuracy, useSystem.nanoTime()
directly instead.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"
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)
orcreateStarted(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(); // requires API Level 17 } });
- Since:
- 10.0
- Author:
- Kevin Bourrillion
- The raw
-
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description static Stopwatch
createStarted()
Creates (and starts) a new stopwatch usingSystem.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 usingSystem.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()
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.
-
-
-
Method Detail
-
createUnstarted
public static Stopwatch createUnstarted()
Creates (but does not start) a new stopwatch usingSystem.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 usingSystem.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()
-
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.
-
reset
@CanIgnoreReturnValue 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(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
public java.lang.String toString()
Returns a string representation of the current elapsed time.- Overrides:
toString
in classjava.lang.Object
-
-