com.nytimes.android.external.cache

Class Stopwatch

java.lang.Object

com.nytimes.android.external.cache.Stopwatch

public final class Stopwatch
extends java.lang.Object

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 by nanoTime 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

   long millis = stopwatch.elapsed(MILLISECONDS);

   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.

Since:

10.0

Method Summary

Modifier and Type	Method and Description
static Stopwatch	createStarted() Creates (and starts) a new stopwatch using System.nanoTime() as its time source.
static Stopwatch	createUnstarted() Creates (but does not start) a new stopwatch using System.nanoTime() as its time source.
Stopwatch	start() Starts the stopwatch.
Stopwatch	stop() Stops the stopwatch.
java.lang.String	toString() Returns a string representation of the current elapsed time.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Method Detail

createUnstarted

@Nonnull
public static Stopwatch createUnstarted()

Creates (but does not start) a new stopwatch using System.nanoTime() as its time source.

Since:

15.0

createStarted

@Nonnull
public static Stopwatch createStarted()

Creates (and starts) a new stopwatch using System.nanoTime() as its time source.

Since:

15.0

start

@Nonnull
public Stopwatch start()

Starts the stopwatch.

Returns:

this Stopwatch instance

Throws:

java.lang.IllegalStateException - if the stopwatch is already running.

stop

@Nonnull
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.

toString

public java.lang.String toString()

Returns a string representation of the current elapsed time.

Overrides:

toString in class java.lang.Object