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 java.time.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.

The one downside of Stopwatch relative to System#nanoTime() is that Stopwatch 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, use System.nanoTime() directly instead.

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.

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
       }
     });