001    /*
002     * Copyright (C) 2008 The Guava Authors
003     *
004     * Licensed under the Apache License, Version 2.0 (the "License");
005     * you may not use this file except in compliance with the License.
006     * You may obtain a copy of the License at
007     *
008     * http://www.apache.org/licenses/LICENSE-2.0
009     *
010     * Unless required by applicable law or agreed to in writing, software
011     * distributed under the License is distributed on an "AS IS" BASIS,
012     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013     * See the License for the specific language governing permissions and
014     * limitations under the License.
015     */
016    
017    package com.google.common.base;
018    
019    import static com.google.common.base.Preconditions.checkNotNull;
020    import static com.google.common.base.Preconditions.checkState;
021    import static java.util.concurrent.TimeUnit.MICROSECONDS;
022    import static java.util.concurrent.TimeUnit.MILLISECONDS;
023    import static java.util.concurrent.TimeUnit.NANOSECONDS;
024    import static java.util.concurrent.TimeUnit.SECONDS;
025    
026    import com.google.common.annotations.Beta;
027    import com.google.common.annotations.GwtCompatible;
028    import com.google.common.annotations.GwtIncompatible;
029    
030    import java.util.concurrent.TimeUnit;
031    
032    /**
033     * An object that measures elapsed time in nanoseconds. It is useful to measure
034     * elapsed time using this class instead of direct calls to {@link
035     * System#nanoTime} for a few reasons:
036     *
037     * <ul>
038     * <li>An alternate time source can be substituted, for testing or performance
039     *     reasons.
040     * <li>As documented by {@code nanoTime}, the value returned has no absolute
041     *     meaning, and can only be interpreted as relative to another timestamp
042     *     returned by {@code nanoTime} at a different time. {@code Stopwatch} is a
043     *     more effective abstraction because it exposes only these relative values,
044     *     not the absolute ones.
045     * </ul>
046     *
047     * <p>Basic usage:
048     * <pre>
049     *   Stopwatch stopwatch = new Stopwatch().{@link #start start}();
050     *   doSomething();
051     *   stopwatch.{@link #stop stop}(); // optional
052     *
053     *   long millis = stopwatch.{@link #elapsedMillis elapsedMillis}();
054     *
055     *   log.info("that took: " + stopwatch); // formatted string like "12.3 ms"
056     * </pre>
057     *
058     * <p>Stopwatch methods are not idempotent; it is an error to start or stop a
059     * stopwatch that is already in the desired state.
060     *
061     * <p>When testing code that uses this class, use the {@linkplain
062     * #Stopwatch(Ticker) alternate constructor} to supply a fake or mock ticker.
063     * <!-- TODO(kevinb): restore the "such as" --> This allows you to
064     * simulate any valid behavior of the stopwatch.
065     *
066     * <p><b>Note:</b> This class is not thread-safe.
067     *
068     * @author Kevin Bourrillion
069     * @since 10.0
070     */
071    @Beta
072    @GwtCompatible(emulated=true)
073    public final class Stopwatch {
074      private final Ticker ticker;
075      private boolean isRunning;
076      private long elapsedNanos;
077      private long startTick;
078    
079      /**
080       * Creates (but does not start) a new stopwatch using {@link System#nanoTime}
081       * as its time source.
082       */
083      public Stopwatch() {
084        this(Ticker.systemTicker());
085      }
086    
087      /**
088       * Creates (but does not start) a new stopwatch, using the specified time
089       * source.
090       */
091      public Stopwatch(Ticker ticker) {
092        this.ticker = checkNotNull(ticker);
093      }
094    
095      /**
096       * Returns {@code true} if {@link #start()} has been called on this stopwatch,
097       * and {@link #stop()} has not been called since the last call to {@code
098       * start()}.
099       */
100      public boolean isRunning() {
101        return isRunning;
102      }
103    
104      /**
105       * Starts the stopwatch.
106       *
107       * @return this {@code Stopwatch} instance
108       * @throws IllegalStateException if the stopwatch is already running.
109       */
110      public Stopwatch start() {
111        checkState(!isRunning);
112        isRunning = true;
113        startTick = ticker.read();
114        return this;
115      }
116    
117      /**
118       * Stops the stopwatch. Future reads will return the fixed duration that had
119       * elapsed up to this point.
120       *
121       * @return this {@code Stopwatch} instance
122       * @throws IllegalStateException if the stopwatch is already stopped.
123       */
124      public Stopwatch stop() {
125        long tick = ticker.read();
126        checkState(isRunning);
127        isRunning = false;
128        elapsedNanos += tick - startTick;
129        return this;
130      }
131    
132      /**
133       * Sets the elapsed time for this stopwatch to zero,
134       * and places it in a stopped state.
135       *
136       * @return this {@code Stopwatch} instance
137       */
138      public Stopwatch reset() {
139        elapsedNanos = 0;
140        isRunning = false;
141        return this;
142      }
143    
144      private long elapsedNanos() {
145        return isRunning ? ticker.read() - startTick + elapsedNanos : elapsedNanos;
146      }
147    
148      /**
149       * Returns the current elapsed time shown on this stopwatch, expressed
150       * in the desired time unit, with any fraction rounded down.
151       *
152       * <p>Note that the overhead of measurement can be more than a microsecond, so
153       * it is generally not useful to specify {@link TimeUnit#NANOSECONDS}
154       * precision here.
155       */
156      public long elapsedTime(TimeUnit desiredUnit) {
157        return desiredUnit.convert(elapsedNanos(), NANOSECONDS);
158      }
159    
160      /**
161       * Returns the current elapsed time shown on this stopwatch, expressed
162       * in milliseconds, with any fraction rounded down. This is identical to
163       * {@code elapsedTime(TimeUnit.MILLISECONDS}.
164       */
165      public long elapsedMillis() {
166        return elapsedTime(MILLISECONDS);
167      }
168    
169      /**
170       * Returns a string representation of the current elapsed time.
171       */
172      @GwtIncompatible("String.format()")
173      @Override public String toString() {
174        return toString(4);
175      }
176    
177      /**
178       * Returns a string representation of the current elapsed time, choosing an
179       * appropriate unit and using the specified number of significant figures.
180       * For example, at the instant when {@code elapsedTime(NANOSECONDS)} would
181       * return {1234567}, {@code toString(4)} returns {@code "1.235 ms"}.
182       *
183       * @deprecated Use {@link #toString()} instead. This method is scheduled
184       *     to be removed in Guava release 15.0.
185       */
186      @Deprecated
187      @GwtIncompatible("String.format()")
188      public String toString(int significantDigits) {
189        long nanos = elapsedNanos();
190    
191        TimeUnit unit = chooseUnit(nanos);
192        double value = (double) nanos / NANOSECONDS.convert(1, unit);
193    
194        // Too bad this functionality is not exposed as a regular method call
195        return String.format("%." + significantDigits + "g %s",
196            value, abbreviate(unit));
197      }
198    
199      private static TimeUnit chooseUnit(long nanos) {
200        if (SECONDS.convert(nanos, NANOSECONDS) > 0) {
201          return SECONDS;
202        }
203        if (MILLISECONDS.convert(nanos, NANOSECONDS) > 0) {
204          return MILLISECONDS;
205        }
206        if (MICROSECONDS.convert(nanos, NANOSECONDS) > 0) {
207          return MICROSECONDS;
208        }
209        return NANOSECONDS;
210      }
211    
212      private static String abbreviate(TimeUnit unit) {
213        switch (unit) {
214          case NANOSECONDS:
215            return "ns";
216          case MICROSECONDS:
217            return "\u03bcs"; // μs
218          case MILLISECONDS:
219            return "ms";
220          case SECONDS:
221            return "s";
222          default:
223            throw new AssertionError();
224        }
225      }
226    }