Class Stopwatch
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
longvalues returned bynanoTimeare meaningless and unsafe to use in any other way than howStopwatchuses 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(); // requires API Level 17
}
});
- Since:
- 10.0
-
Field Summary
Fields -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionprivate static Stringabbreviate(TimeUnit unit) private static TimeUnitchooseUnit(long nanos) static StopwatchCreates (and starts) a new stopwatch usingSystem.nanoTime()as its time source.static StopwatchcreateStarted(Ticker ticker) Creates (and starts) a new stopwatch, using the specified time source.static StopwatchCreates (but does not start) a new stopwatch usingSystem.nanoTime()as its time source.static StopwatchcreateUnstarted(Ticker ticker) Creates (but does not start) a new stopwatch, using the specified time source.elapsed()Returns the current elapsed time shown on this stopwatch as aDuration.longReturns the current elapsed time shown on this stopwatch, expressed in the desired time unit, with any fraction rounded down.private longbooleanreset()Sets the elapsed time for this stopwatch to zero, and places it in a stopped state.start()Starts the stopwatch.stop()Stops the stopwatch.toString()Returns a string representation of the current elapsed time.
-
Field Details
-
ticker
-
isRunning
private boolean isRunning -
elapsedNanos
private long elapsedNanos -
startTick
private long startTick
-
-
Constructor Details
-
Stopwatch
Stopwatch() -
Stopwatch
Stopwatch(Ticker ticker)
-
-
Method Details
-
createUnstarted
Creates (but does not start) a new stopwatch usingSystem.nanoTime()as its time source.- Since:
- 15.0
-
createUnstarted
Creates (but does not start) a new stopwatch, using the specified time source.- Since:
- 15.0
-
createStarted
Creates (and starts) a new stopwatch usingSystem.nanoTime()as its time source.- Since:
- 15.0
-
createStarted
Creates (and starts) a new stopwatch, using the specified time source.- Since:
- 15.0
-
isRunning
public boolean isRunning() -
start
Starts the stopwatch.- Returns:
- this
Stopwatchinstance - Throws:
IllegalStateException- if the stopwatch is already running.
-
stop
Stops the stopwatch. Future reads will return the fixed duration that had elapsed up to this point.- Returns:
- this
Stopwatchinstance - Throws:
IllegalStateException- if the stopwatch is already stopped.
-
reset
Sets the elapsed time for this stopwatch to zero, and places it in a stopped state.- Returns:
- this
Stopwatchinstance
-
elapsedNanos
private long elapsedNanos() -
elapsed
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.NANOSECONDSprecision here.It is generally not a good idea to use an ambiguous, unitless
longto represent elapsed time. Therefore, we recommend usingelapsed()instead, which returns a strongly-typedDurationinstance.- Since:
- 14.0 (since 10.0 as
elapsedTime())
-
elapsed
Returns the current elapsed time shown on this stopwatch as aDuration. Unlikeelapsed(TimeUnit), this method does not lose any precision due to rounding.- Since:
- 22.0
-
toString
Returns a string representation of the current elapsed time. -
chooseUnit
-
abbreviate
-