1 files changed, 226 insertions, 0 deletions
diff --git a/guava/src/com/google/common/base/Stopwatch.java b/guava/src/com/google/common/base/Stopwatch.java
new file mode 100644
index 0000000..9e1b6f6
--- /dev/null
+++ b/guava/src/com/google/common/base/Stopwatch.java
@@ -0,0 +1,226 @@
+/*
+ * Copyright (C) 2008 The Guava Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.google.common.base;
+
+import static com.google.common.base.Preconditions.checkNotNull;
+import static com.google.common.base.Preconditions.checkState;
+import static java.util.concurrent.TimeUnit.MICROSECONDS;
+import static java.util.concurrent.TimeUnit.MILLISECONDS;
+import static java.util.concurrent.TimeUnit.NANOSECONDS;
+import static java.util.concurrent.TimeUnit.SECONDS;
+
+import com.google.common.annotations.Beta;
+import com.google.common.annotations.GwtCompatible;
+import com.google.common.annotations.GwtIncompatible;
+
+import java.util.concurrent.TimeUnit;
+
+/**
+ * An object that measures elapsed time in nanoseconds. It is useful to measure
+ * elapsed time using this class instead of direct calls to {@link
+ * System#nanoTime} for a few reasons:
+ *
+ * <ul>
+ * <li>An alternate time source can be substituted, for testing or performance
+ *     reasons.
+ * <li>As documented by {@code nanoTime}, the value returned has no absolute
+ *     meaning, and can only be interpreted as relative to another timestamp
+ *     returned by {@code nanoTime} at a different time. {@code Stopwatch} is a
+ *     more effective abstraction because it exposes only these relative values,
+ *     not the absolute ones.
+ * </ul>
+ *
+ * <p>Basic usage:
+ * <pre>
+ *   Stopwatch stopwatch = new Stopwatch().{@link #start start}();
+ *   doSomething();
+ *   stopwatch.{@link #stop stop}(); // optional
+ *
+ *   long millis = stopwatch.{@link #elapsedMillis elapsedMillis}();
+ *
+ *   log.info("that took: " + stopwatch); // formatted string like "12.3 ms"
+ * </pre>
+ *
+ * <p>Stopwatch methods are not idempotent; it is an error to start or stop a
+ * stopwatch that is already in the desired state.
+ *
+ * <p>When testing code that uses this class, use the {@linkplain
+ * #Stopwatch(Ticker) alternate constructor} to supply a fake or mock ticker.
+ * <!-- TODO(kevinb): restore the "such as" --> This allows you to
+ * simulate any valid behavior of the stopwatch.
+ *
+ * <p><b>Note:</b> This class is not thread-safe.
+ *
+ * @author Kevin Bourrillion
+ * @since 10.0
+ */
+@Beta
+@GwtCompatible(emulated=true)
+public final class Stopwatch {
+  private final Ticker ticker;
+  private boolean isRunning;
+  private long elapsedNanos;
+  private long startTick;
+
+  /**
+   * Creates (but does not start) a new stopwatch using {@link System#nanoTime}
+   * as its time source.
+   */
+  public Stopwatch() {
+    this(Ticker.systemTicker());
+  }
+
+  /**
+   * Creates (but does not start) a new stopwatch, using the specified time
+   * source.
+   */
+  public Stopwatch(Ticker ticker) {
+    this.ticker = checkNotNull(ticker);
+  }
+
+  /**
+   * Returns {@code true} if {@link #start()} has been called on this stopwatch,
+   * and {@link #stop()} has not been called since the last call to {@code
+   * start()}.
+   */
+  public boolean isRunning() {
+    return isRunning;
+  }
+
+  /**
+   * Starts the stopwatch.
+   *
+   * @return this {@code Stopwatch} instance
+   * @throws IllegalStateException if the stopwatch is already running.
+   */
+  public Stopwatch start() {
+    checkState(!isRunning);
+    isRunning = true;
+    startTick = ticker.read();
+    return this;
+  }
+
+  /**
+   * Stops the stopwatch. Future reads will return the fixed duration that had
+   * elapsed up to this point.
+   *
+   * @return this {@code Stopwatch} instance
+   * @throws IllegalStateException if the stopwatch is already stopped.
+   */
+  public Stopwatch stop() {
+    long tick = ticker.read();
+    checkState(isRunning);
+    isRunning = false;
+    elapsedNanos += tick - startTick;
+    return this;
+  }
+
+  /**
+   * Sets the elapsed time for this stopwatch to zero,
+   * and places it in a stopped state.
+   *
+   * @return this {@code Stopwatch} instance
+   */
+  public Stopwatch reset() {
+    elapsedNanos = 0;
+    isRunning = false;
+    return this;
+  }
+
+  private long elapsedNanos() {
+    return isRunning ? ticker.read() - startTick + elapsedNanos : elapsedNanos;
+  }
+
+  /**
+   * Returns the current elapsed time shown on this stopwatch, expressed
+   * in the desired time unit, with any fraction rounded down.
+   *
+   * <p>Note that the overhead of measurement can be more than a microsecond, so
+   * it is generally not useful to specify {@link TimeUnit#NANOSECONDS}
+   * precision here.
+   */
+  public long elapsedTime(TimeUnit desiredUnit) {
+    return desiredUnit.convert(elapsedNanos(), NANOSECONDS);
+  }
+
+  /**
+   * Returns the current elapsed time shown on this stopwatch, expressed
+   * in milliseconds, with any fraction rounded down. This is identical to
+   * {@code elapsedTime(TimeUnit.MILLISECONDS}.
+   */
+  public long elapsedMillis() {
+    return elapsedTime(MILLISECONDS);
+  }
+
+  /**
+   * Returns a string representation of the current elapsed time.
+   */
+  @GwtIncompatible("String.format()")
+  @Override public String toString() {
+    return toString(4);
+  }
+
+  /**
+   * Returns a string representation of the current elapsed time, choosing an
+   * appropriate unit and using the specified number of significant figures.
+   * For example, at the instant when {@code elapsedTime(NANOSECONDS)} would
+   * return {1234567}, {@code toString(4)} returns {@code "1.235 ms"}.
+   *
+   * @deprecated Use {@link #toString()} instead. This method is scheduled
+   *     to be removed in Guava release 15.0.
+   */
+  @Deprecated
+  @GwtIncompatible("String.format()")
+  public String toString(int significantDigits) {
+    long nanos = elapsedNanos();
+
+    TimeUnit unit = chooseUnit(nanos);
+    double value = (double) nanos / NANOSECONDS.convert(1, unit);
+
+    // Too bad this functionality is not exposed as a regular method call
+    return String.format("%." + significantDigits + "g %s",
+        value, abbreviate(unit));
+  }
+
+  private static TimeUnit chooseUnit(long nanos) {
+    if (SECONDS.convert(nanos, NANOSECONDS) > 0) {
+      return SECONDS;
+    }
+    if (MILLISECONDS.convert(nanos, NANOSECONDS) > 0) {
+      return MILLISECONDS;
+    }
+    if (MICROSECONDS.convert(nanos, NANOSECONDS) > 0) {
+      return MICROSECONDS;
+    }
+    return NANOSECONDS;
+  }
+
+  private static String abbreviate(TimeUnit unit) {
+    switch (unit) {
+      case NANOSECONDS:
+        return "ns";
+      case MICROSECONDS:
+        return "\u03bcs"; // μs
+      case MILLISECONDS:
+        return "ms";
+      case SECONDS:
+        return "s";
+      default:
+        throw new AssertionError();
+    }
+  }
+}