1/* 2 * Copyright (C) 2008 The Guava Authors 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17package com.google.common.base; 18 19import static com.google.common.base.Preconditions.checkNotNull; 20import static com.google.common.base.Preconditions.checkState; 21import static java.util.concurrent.TimeUnit.DAYS; 22import static java.util.concurrent.TimeUnit.HOURS; 23import static java.util.concurrent.TimeUnit.MICROSECONDS; 24import static java.util.concurrent.TimeUnit.MILLISECONDS; 25import static java.util.concurrent.TimeUnit.MINUTES; 26import static java.util.concurrent.TimeUnit.NANOSECONDS; 27import static java.util.concurrent.TimeUnit.SECONDS; 28 29import com.google.common.annotations.Beta; 30import com.google.common.annotations.GwtCompatible; 31import com.google.common.annotations.GwtIncompatible; 32 33import java.util.concurrent.TimeUnit; 34 35/** 36 * An object that measures elapsed time in nanoseconds. It is useful to measure 37 * elapsed time using this class instead of direct calls to {@link 38 * System#nanoTime} for a few reasons: 39 * 40 * <ul> 41 * <li>An alternate time source can be substituted, for testing or performance 42 * reasons. 43 * <li>As documented by {@code nanoTime}, the value returned has no absolute 44 * meaning, and can only be interpreted as relative to another timestamp 45 * returned by {@code nanoTime} at a different time. {@code Stopwatch} is a 46 * more effective abstraction because it exposes only these relative values, 47 * not the absolute ones. 48 * </ul> 49 * 50 * <p>Basic usage: 51 * <pre> 52 * Stopwatch stopwatch = Stopwatch.{@link #createStarted createStarted}(); 53 * doSomething(); 54 * stopwatch.{@link #stop stop}(); // optional 55 * 56 * long millis = stopwatch.elapsed(MILLISECONDS); 57 * 58 * log.info("time: " + stopwatch); // formatted string like "12.3 ms"</pre> 59 * 60 * <p>Stopwatch methods are not idempotent; it is an error to start or stop a 61 * stopwatch that is already in the desired state. 62 * 63 * <p>When testing code that uses this class, use 64 * {@link #createUnstarted(Ticker)} or {@link #createStarted(Ticker)} to 65 * supply a fake or mock ticker. 66 * <!-- TODO(kevinb): restore the "such as" --> This allows you to 67 * simulate any valid behavior of the stopwatch. 68 * 69 * <p><b>Note:</b> This class is not thread-safe. 70 * 71 * @author Kevin Bourrillion 72 * @since 10.0 73 */ 74@Beta 75@GwtCompatible(emulated = true) 76public final class Stopwatch { 77 private final Ticker ticker; 78 private boolean isRunning; 79 private long elapsedNanos; 80 private long startTick; 81 82 /** 83 * Creates (but does not start) a new stopwatch using {@link System#nanoTime} 84 * as its time source. 85 * 86 * @since 15.0 87 */ 88 public static Stopwatch createUnstarted() { 89 return new Stopwatch(); 90 } 91 92 /** 93 * Creates (but does not start) a new stopwatch, using the specified time 94 * source. 95 * 96 * @since 15.0 97 */ 98 public static Stopwatch createUnstarted(Ticker ticker) { 99 return new Stopwatch(ticker); 100 } 101 102 /** 103 * Creates (and starts) a new stopwatch using {@link System#nanoTime} 104 * as its time source. 105 * 106 * @since 15.0 107 */ 108 public static Stopwatch createStarted() { 109 return new Stopwatch().start(); 110 } 111 112 /** 113 * Creates (and starts) a new stopwatch, using the specified time 114 * source. 115 * 116 * @since 15.0 117 */ 118 public static Stopwatch createStarted(Ticker ticker) { 119 return new Stopwatch(ticker).start(); 120 } 121 122 /** 123 * Creates (but does not start) a new stopwatch using {@link System#nanoTime} 124 * as its time source. 125 * 126 * @deprecated Use {@link Stopwatch#createUnstarted()} instead. 127 */ 128 @Deprecated 129 Stopwatch() { 130 this(Ticker.systemTicker()); 131 } 132 133 /** 134 * Creates (but does not start) a new stopwatch, using the specified time 135 * source. 136 * 137 * @deprecated Use {@link Stopwatch#createUnstarted(Ticker)} instead. 138 */ 139 @Deprecated 140 Stopwatch(Ticker ticker) { 141 this.ticker = checkNotNull(ticker, "ticker"); 142 } 143 144 /** 145 * Returns {@code true} if {@link #start()} has been called on this stopwatch, 146 * and {@link #stop()} has not been called since the last call to {@code 147 * start()}. 148 */ 149 public boolean isRunning() { 150 return isRunning; 151 } 152 153 /** 154 * Starts the stopwatch. 155 * 156 * @return this {@code Stopwatch} instance 157 * @throws IllegalStateException if the stopwatch is already running. 158 */ 159 public Stopwatch start() { 160 checkState(!isRunning, "This stopwatch is already running."); 161 isRunning = true; 162 startTick = ticker.read(); 163 return this; 164 } 165 166 /** 167 * Stops the stopwatch. Future reads will return the fixed duration that had 168 * elapsed up to this point. 169 * 170 * @return this {@code Stopwatch} instance 171 * @throws IllegalStateException if the stopwatch is already stopped. 172 */ 173 public Stopwatch stop() { 174 long tick = ticker.read(); 175 checkState(isRunning, "This stopwatch is already stopped."); 176 isRunning = false; 177 elapsedNanos += tick - startTick; 178 return this; 179 } 180 181 /** 182 * Sets the elapsed time for this stopwatch to zero, 183 * and places it in a stopped state. 184 * 185 * @return this {@code Stopwatch} instance 186 */ 187 public Stopwatch reset() { 188 elapsedNanos = 0; 189 isRunning = false; 190 return this; 191 } 192 193 private long elapsedNanos() { 194 return isRunning ? ticker.read() - startTick + elapsedNanos : elapsedNanos; 195 } 196 197 /** 198 * Returns the current elapsed time shown on this stopwatch, expressed 199 * in the desired time unit, with any fraction rounded down. 200 * 201 * <p>Note that the overhead of measurement can be more than a microsecond, so 202 * it is generally not useful to specify {@link TimeUnit#NANOSECONDS} 203 * precision here. 204 * 205 * @since 14.0 (since 10.0 as {@code elapsedTime()}) 206 */ 207 public long elapsed(TimeUnit desiredUnit) { 208 return desiredUnit.convert(elapsedNanos(), NANOSECONDS); 209 } 210 211 /** 212 * Returns a string representation of the current elapsed time. 213 */ 214 @GwtIncompatible("String.format()") 215 @Override public String toString() { 216 long nanos = elapsedNanos(); 217 218 TimeUnit unit = chooseUnit(nanos); 219 double value = (double) nanos / NANOSECONDS.convert(1, unit); 220 221 // Too bad this functionality is not exposed as a regular method call 222 return String.format("%.4g %s", value, abbreviate(unit)); 223 } 224 225 private static TimeUnit chooseUnit(long nanos) { 226 if (DAYS.convert(nanos, NANOSECONDS) > 0) { 227 return DAYS; 228 } 229 if (HOURS.convert(nanos, NANOSECONDS) > 0) { 230 return HOURS; 231 } 232 if (MINUTES.convert(nanos, NANOSECONDS) > 0) { 233 return MINUTES; 234 } 235 if (SECONDS.convert(nanos, NANOSECONDS) > 0) { 236 return SECONDS; 237 } 238 if (MILLISECONDS.convert(nanos, NANOSECONDS) > 0) { 239 return MILLISECONDS; 240 } 241 if (MICROSECONDS.convert(nanos, NANOSECONDS) > 0) { 242 return MICROSECONDS; 243 } 244 return NANOSECONDS; 245 } 246 247 private static String abbreviate(TimeUnit unit) { 248 switch (unit) { 249 case NANOSECONDS: 250 return "ns"; 251 case MICROSECONDS: 252 return "\u03bcs"; // μs 253 case MILLISECONDS: 254 return "ms"; 255 case SECONDS: 256 return "s"; 257 case MINUTES: 258 return "min"; 259 case HOURS: 260 return "h"; 261 case DAYS: 262 return "d"; 263 default: 264 throw new AssertionError(); 265 } 266 } 267} 268