java stopwatch_java stopwatch 功能

1 /*

2 * Copyright (C) 2008 The Guava Authors3 *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 at7 *8 *http://www.apache.org/licenses/LICENSE-2.0

9 *10 * Unless required by applicable law or agreed to in writing, software11 * 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 and14 * limitations under the License.15 */

16

17 packagecom.google.common.base;18

19 import staticcom.google.common.base.Preconditions.checkNotNull;20 import staticcom.google.common.base.Preconditions.checkState;21 import staticjava.util.concurrent.TimeUnit.MICROSECONDS;22 import staticjava.util.concurrent.TimeUnit.MILLISECONDS;23 import staticjava.util.concurrent.TimeUnit.NANOSECONDS;24 import staticjava.util.concurrent.TimeUnit.SECONDS;25

26 importcom.google.common.annotations.Beta;27 importcom.google.common.annotations.GwtCompatible;28 importcom.google.common.annotations.GwtIncompatible;29

30 importjava.util.concurrent.TimeUnit;31

32 /**

33 * An object that measures elapsed time in nanoseconds. It is useful to measure34 * elapsed time using this class instead of direct calls to {@link

35 * System#nanoTime} for a few reasons:36 *37 *

• 38 *
• An alternate time source can be substituted, for testing or performance39 * reasons.40 *
• As documented by {@codenanoTime}, the value returned has no absolute41 * meaning, and can only be interpreted as relative to another timestamp42 * returned by {@codenanoTime} at a different time. {@codeStopwatch} is a43 * more effective abstraction because it exposes only these relative values,44 * not the absolute ones.45 *

46 *47 *

Basic usage:48 *

49 *   Stopwatch stopwatch = new Stopwatch().{@link#start start}();50 *   doSomething();51 *   stopwatch.{@link#stop stop}(); // optional52 *53 *   long millis = stopwatch.elapsed(MILLISECONDS);54 *55 *   log.info("that took: " + stopwatch); // formatted string like "12.3 ms"56 * 

57 *58 *

Stopwatch methods are not idempotent; it is an error to start or stop a59 * stopwatch that is already in the desired state.60 *61 *

When testing code that uses this class, use the {@linkplain

62 * #Stopwatch(Ticker) alternate constructor} to supply a fake or mock ticker.63 * This allows you to64 * simulate any valid behavior of the stopwatch.65 *66 *

Note: This class is not thread-safe.67 *68 *@authorKevin Bourrillion69 *@since10.070 */

71 @Beta72 @GwtCompatible(emulated = true)73 public final classStopwatch {74 private finalTicker ticker;75 private booleanisRunning;76 private longelapsedNanos;77 private longstartTick;78

79 /**

80 * Creates (but does not start) a new stopwatch using {@linkSystem#nanoTime}81 * as its time source.82 */

83 publicStopwatch() {84 this(Ticker.systemTicker());85 }86

87 /**

88 * Creates (but does not start) a new stopwatch, using the specified time89 * source.90 */

91 publicStopwatch(Ticker ticker) {92 this.ticker = checkNotNull(ticker, "ticker");93 }94

95 /**

96 * Returns {@codetrue} if {@link#start()} has been called on this stopwatch,97 * and {@link#stop()} has not been called since the last call to {@code

98 * start()}.99 */

100 public booleanisRunning() {101 returnisRunning;102 }103

104 /**

105 * Starts the stopwatch.106 *107 *@returnthis {@codeStopwatch} instance108 *@throwsIllegalStateException if the stopwatch is already running.109 */

110 publicStopwatch start() {111 checkState(!isRunning,112 "This stopwatch is already running; it cannot be started more than once.");113 isRunning = true;114 startTick =ticker.read();115 return this;116 }117

118 /**

119 * Stops the stopwatch. Future reads will return the fixed duration that had120 * elapsed up to this point.121 *122 *@returnthis {@codeStopwatch} instance123 *@throwsIllegalStateException if the stopwatch is already stopped.124 */

125 publicStopwatch stop() {126 long tick =ticker.read();127 checkState(isRunning,128 "This stopwatch is already stopped; it cannot be stopped more than once.");129 isRunning = false;130 elapsedNanos += tick -startTick;131 return this;132 }133

134 /**

135 * Sets the elapsed time for this stopwatch to zero,136 * and places it in a stopped state.137 *138 *@returnthis {@codeStopwatch} instance139 */

140 publicStopwatch reset() {141 elapsedNanos = 0;142 isRunning = false;143 return this;144 }145

146 private longelapsedNanos() {147 return isRunning ? ticker.read() - startTick +elapsedNanos : elapsedNanos;148 }149

150 /**

151 * Returns the current elapsed time shown on this stopwatch, expressed152 * in the desired time unit, with any fraction rounded down.153 *154 *

Note that the overhead of measurement can be more than a microsecond, so155 * it is generally not useful to specify {@linkTimeUnit#NANOSECONDS}156 * precision here.157 *158 *@since14.0 (since 10.0 as {@codeelapsedTime()})159 */

160 public longelapsed(TimeUnit desiredUnit) {161 returndesiredUnit.convert(elapsedNanos(), NANOSECONDS);162 }163

164 /**

165 * Returns the current elapsed time shown on this stopwatch, expressed166 * in the desired time unit, with any fraction rounded down.167 *168 *

Note that the overhead of measurement can be more than a microsecond, so169 * it is generally not useful to specify {@linkTimeUnit#NANOSECONDS}170 * precision here.171 *172 *@deprecatedUse {@linkStopwatch#elapsed(TimeUnit)} instead. This method is173 * scheduled to be removed in Guava release 16.0.174 */

175 @Deprecated176 public longelapsedTime(TimeUnit desiredUnit) {177 returnelapsed(desiredUnit);178 }179

180 /**

181 * Returns the current elapsed time shown on this stopwatch, expressed182 * in milliseconds, with any fraction rounded down. This is identical to183 * {@codeelapsed(TimeUnit.MILLISECONDS)}.184 *185 *@deprecatedUse {@codestopwatch.elapsed(MILLISECONDS)} instead. This186 * method is scheduled to be removed in Guava release 16.0.187 */

188 @Deprecated189 public longelapsedMillis() {190 returnelapsed(MILLISECONDS);191 }192

193 /**

194 * Returns a string representation of the current elapsed time.195 */

196 @GwtIncompatible("String.format()")197 @Override publicString toString() {198 return toString(4);199 }200

201 /**

202 * Returns a string representation of the current elapsed time, choosing an203 * appropriate unit and using the specified number of significant figures.204 * For example, at the instant when {@codeelapsed(NANOSECONDS)} would205 * return {1234567}, {@codetoString(4)} returns {@code"1.235 ms"}.206 *207 *@deprecatedUse {@link#toString()} instead. This method is scheduled208 * to be removed in Guava release 15.0.209 */

210 @Deprecated211 @GwtIncompatible("String.format()")212 public String toString(intsignificantDigits) {213 long nanos =elapsedNanos();214

215 TimeUnit unit =chooseUnit(nanos);216 double value = (double) nanos / NANOSECONDS.convert(1, unit);217

218 //Too bad this functionality is not exposed as a regular method call

219 return String.format("%." + significantDigits + "g %s",220 value, abbreviate(unit));221 }222

223 private static TimeUnit chooseUnit(longnanos) {224 if (SECONDS.convert(nanos, NANOSECONDS) > 0) {225 returnSECONDS;226 }227 if (MILLISECONDS.convert(nanos, NANOSECONDS) > 0) {228 returnMILLISECONDS;229 }230 if (MICROSECONDS.convert(nanos, NANOSECONDS) > 0) {231 returnMICROSECONDS;232 }233 returnNANOSECONDS;234 }235

236 private staticString abbreviate(TimeUnit unit) {237 switch(unit) {238 caseNANOSECONDS:239 return "ns";240 caseMICROSECONDS:241 return "\u03bcs"; //渭s

242 caseMILLISECONDS:243 return "ms";244 caseSECONDS:245 return "s";246 default:247 throw newAssertionError();248 }249 }250 }