Merge remote-tracking branch 'aosp/upstream-master' into merge am: dd3cabeacc

am: 6fbc3cf5a1

Change-Id: I11b0ec1cf561d2a14da78e444b1594f167787fe6

1 files changed, 136 insertions, 0 deletions

diff --git a/api/src/main/java/io/opencensus/common/Duration.java b/api/src/main/java/io/opencensus/common/Duration.java
new file mode 100644
index 00000000..f46cd187
--- /dev/null
+++ b/api/src/main/java/io/opencensus/common/Duration.java
@@ -0,0 +1,136 @@
+/*
+ * Copyright 2016-17, OpenCensus 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 io.opencensus.common;
+
+import static io.opencensus.common.TimeUtils.MAX_NANOS;
+import static io.opencensus.common.TimeUtils.MAX_SECONDS;
+import static io.opencensus.common.TimeUtils.MILLIS_PER_SECOND;
+import static io.opencensus.common.TimeUtils.NANOS_PER_MILLI;
+
+import com.google.auto.value.AutoValue;
+import java.util.concurrent.TimeUnit;
+import javax.annotation.concurrent.Immutable;
+
+/**
+ * Represents a signed, fixed-length span of time represented as a count of seconds and fractions of
+ * seconds at nanosecond resolution. It is independent of any calendar and concepts like "day" or
+ * "month". Range is approximately +-10,000 years.
+ *
+ * @since 0.5
+ */
+@Immutable
+@AutoValue
+public abstract class Duration implements Comparable<Duration> {
+
+  /**
+   * Creates a new time duration from given seconds and nanoseconds.
+   *
+   * @param seconds Signed seconds of the span of time. Must be from -315,576,000,000 to
+   *     +315,576,000,000 inclusive.
+   * @param nanos Signed fractions of a second at nanosecond resolution of the span of time.
+   *     Durations less than one second are represented with a 0 `seconds` field and a positive or
+   *     negative `nanos` field. For durations of one second or more, a non-zero value for the
+   *     `nanos` field must be of the same sign as the `seconds` field. Must be from -999,999,999 to
+   *     +999,999,999 inclusive.
+   * @return new {@code Duration} with specified fields.
+   * @throws IllegalArgumentException if the arguments are out of range or have inconsistent sign.
+   * @since 0.5
+   */
+  public static Duration create(long seconds, int nanos) {
+    if (seconds < -MAX_SECONDS) {
+      throw new IllegalArgumentException(
+          "'seconds' is less than minimum (" + -MAX_SECONDS + "): " + seconds);
+    }
+    if (seconds > MAX_SECONDS) {
+      throw new IllegalArgumentException(
+          "'seconds' is greater than maximum (" + MAX_SECONDS + "): " + seconds);
+    }
+    if (nanos < -MAX_NANOS) {
+      throw new IllegalArgumentException(
+          "'nanos' is less than minimum (" + -MAX_NANOS + "): " + nanos);
+    }
+    if (nanos > MAX_NANOS) {
+      throw new IllegalArgumentException(
+          "'nanos' is greater than maximum (" + MAX_NANOS + "): " + nanos);
+    }
+    if ((seconds < 0 && nanos > 0) || (seconds > 0 && nanos < 0)) {
+      throw new IllegalArgumentException(
+          "'seconds' and 'nanos' have inconsistent sign: seconds=" + seconds + ", nanos=" + nanos);
+    }
+    return new AutoValue_Duration(seconds, nanos);
+  }
+
+  /**
+   * Creates a new {@code Duration} from given milliseconds.
+   *
+   * @param millis the duration in milliseconds.
+   * @return a new {@code Duration} from given milliseconds.
+   * @throws IllegalArgumentException if the number of milliseconds is out of the range that can be
+   *     represented by {@code Duration}.
+   * @since 0.5
+   */
+  public static Duration fromMillis(long millis) {
+    long seconds = millis / MILLIS_PER_SECOND;
+    int nanos = (int) (millis % MILLIS_PER_SECOND * NANOS_PER_MILLI);
+    return Duration.create(seconds, nanos);
+  }
+
+  /**
+   * Converts a {@link Duration} to milliseconds.
+   *
+   * @return the milliseconds representation of this {@code Duration}.
+   * @since 0.13
+   */
+  public long toMillis() {
+    return TimeUnit.SECONDS.toMillis(getSeconds()) + TimeUnit.NANOSECONDS.toMillis(getNanos());
+  }
+
+  /**
+   * Returns the number of seconds in the {@code Duration}.
+   *
+   * @return the number of seconds in the {@code Duration}.
+   * @since 0.5
+   */
+  public abstract long getSeconds();
+
+  /**
+   * Returns the number of nanoseconds in the {@code Duration}.
+   *
+   * @return the number of nanoseconds in the {@code Duration}.
+   * @since 0.5
+   */
+  public abstract int getNanos();
+
+  /**
+   * Compares this {@code Duration} to the specified {@code Duration}.
+   *
+   * @param otherDuration the other {@code Duration} to compare to, not {@code null}.
+   * @return the comparator value: zero if equal, negative if this duration is smaller than
+   *     otherDuration, positive if larger.
+   * @throws NullPointerException if otherDuration is {@code null}.
+   */
+  @Override
+  public int compareTo(Duration otherDuration) {
+    int cmp = TimeUtils.compareLongs(getSeconds(), otherDuration.getSeconds());
+    if (cmp != 0) {
+      return cmp;
+    }
+    return TimeUtils.compareLongs(getNanos(), otherDuration.getNanos());
+  }
+
+  Duration() {}
+}