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 * @throws IllegalStateException if the stopwatch is already running. 108 */ 109 public Stopwatch start() { 110 checkState(!isRunning); 111 isRunning = true; 112 startTick = ticker.read(); 113 return this; 114 } 115 116 /** 117 * Stops the stopwatch. Future reads will return the fixed duration that had 118 * elapsed up to this point. 119 * 120 * @throws IllegalStateException if the stopwatch is already stopped. 121 */ 122 public Stopwatch stop() { 123 long tick = ticker.read(); 124 checkState(isRunning); 125 isRunning = false; 126 elapsedNanos += tick - startTick; 127 return this; 128 } 129 130 /** 131 * Sets the elapsed time for this stopwatch to zero, 132 * and places it in a stopped state. 133 */ 134 public Stopwatch reset() { 135 elapsedNanos = 0; 136 isRunning = false; 137 return this; 138 } 139 140 private long elapsedNanos() { 141 return isRunning ? ticker.read() - startTick + elapsedNanos : elapsedNanos; 142 } 143 144 /** 145 * Returns the current elapsed time shown on this stopwatch, expressed 146 * in the desired time unit, with any fraction rounded down. 147 * 148 * <p>Note that the overhead of measurement can be more than a microsecond, so 149 * it is generally not useful to specify {@link TimeUnit#NANOSECONDS} 150 * precision here. 151 */ 152 public long elapsedTime(TimeUnit desiredUnit) { 153 return desiredUnit.convert(elapsedNanos(), NANOSECONDS); 154 } 155 156 /** 157 * Returns the current elapsed time shown on this stopwatch, expressed 158 * in milliseconds, with any fraction rounded down. This is identical to 159 * {@code elapsedTime(TimeUnit.MILLISECONDS}. 160 */ 161 public long elapsedMillis() { 162 return elapsedTime(MILLISECONDS); 163 } 164 165 /** 166 * Returns a string representation of the current elapsed time; equivalent to 167 * {@code toString(4)} (four significant figures). 168 */ 169 @GwtIncompatible("String.format()") 170 @Override public String toString() { 171 return toString(4); 172 } 173 174 /** 175 * Returns a string representation of the current elapsed time, choosing an 176 * appropriate unit and using the specified number of significant figures. 177 * For example, at the instant when {@code elapsedTime(NANOSECONDS)} would 178 * return {1234567}, {@code toString(4)} returns {@code "1.235 ms"}. 179 */ 180 @GwtIncompatible("String.format()") 181 public String toString(int significantDigits) { 182 long nanos = elapsedNanos(); 183 184 TimeUnit unit = chooseUnit(nanos); 185 double value = (double) nanos / NANOSECONDS.convert(1, unit); 186 187 // Too bad this functionality is not exposed as a regular method call 188 return String.format("%." + significantDigits + "g %s", 189 value, abbreviate(unit)); 190 } 191 192 private static TimeUnit chooseUnit(long nanos) { 193 if (SECONDS.convert(nanos, NANOSECONDS) > 0) { 194 return SECONDS; 195 } 196 if (MILLISECONDS.convert(nanos, NANOSECONDS) > 0) { 197 return MILLISECONDS; 198 } 199 if (MICROSECONDS.convert(nanos, NANOSECONDS) > 0) { 200 return MICROSECONDS; 201 } 202 return NANOSECONDS; 203 } 204 205 private static String abbreviate(TimeUnit unit) { 206 switch (unit) { 207 case NANOSECONDS: 208 return "ns"; 209 case MICROSECONDS: 210 return "\u03bcs"; // μs 211 case MILLISECONDS: 212 return "ms"; 213 case SECONDS: 214 return "s"; 215 default: 216 throw new AssertionError(); 217 } 218 } 219 }