Class Stopwatch
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 bynanoTime
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.
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
Modifier and TypeMethodDescriptionstatic Stopwatch
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
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.elapsed()
long
Returns the current elapsed time shown on this stopwatch, expressed in the desired time unit, with any fraction rounded down.boolean
reset()
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.
-
Method Details
-
createUnstarted
Creates (but does not start) a new stopwatch usingSystem.nanoTime()
as its time source.- Returns:
- Since:
- 15.0
-
createUnstarted
Creates (but does not start) a new stopwatch, using the specified time source.- Parameters:
ticker
-- Returns:
- Since:
- 15.0
-
createStarted
Creates (and starts) a new stopwatch usingSystem.nanoTime()
as its time source.- Returns:
- Since:
- 15.0
-
createStarted
Creates (and starts) a new stopwatch, using the specified time source.- Parameters:
ticker
-- Returns:
- Since:
- 15.0
-
isRunning
public boolean isRunning()Returnstrue
ifstart()
has been called on this stopwatch, andstop()
has not been called since the last call tostart()
.- Returns:
- true, if is running
-
start
Starts the stopwatch.- Returns:
- this
Stopwatch
instance - 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
Stopwatch
instance - 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
Stopwatch
instance
-
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.NANOSECONDS
precision here.It is generally not a good idea to use an ambiguous, unitless
long
to represent elapsed time. Therefore, we recommend usingelapsed()
instead, which returns a strongly-typedDuration
instance.- Parameters:
desiredUnit
-- Returns:
- Since:
- 14.0 (since 10.0 as
elapsedTime()
)
-
elapsed
-
toString
Returns a string representation of the current elapsed time.
-