1 /* 2 * Copyright 2016-17, OpenCensus 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 17 package io.opencensus.common; 18 19 import static io.opencensus.common.TimeUtils.MAX_NANOS; 20 import static io.opencensus.common.TimeUtils.MAX_SECONDS; 21 import static io.opencensus.common.TimeUtils.MILLIS_PER_SECOND; 22 import static io.opencensus.common.TimeUtils.NANOS_PER_MILLI; 23 24 import com.google.auto.value.AutoValue; 25 import java.util.concurrent.TimeUnit; 26 import javax.annotation.concurrent.Immutable; 27 28 /** 29 * Represents a signed, fixed-length span of time represented as a count of seconds and fractions of 30 * seconds at nanosecond resolution. It is independent of any calendar and concepts like "day" or 31 * "month". Range is approximately +-10,000 years. 32 * 33 * @since 0.5 34 */ 35 @Immutable 36 @AutoValue 37 public abstract class Duration implements Comparable<Duration> { 38 39 /** 40 * Creates a new time duration from given seconds and nanoseconds. 41 * 42 * @param seconds Signed seconds of the span of time. Must be from -315,576,000,000 to 43 * +315,576,000,000 inclusive. 44 * @param nanos Signed fractions of a second at nanosecond resolution of the span of time. 45 * Durations less than one second are represented with a 0 `seconds` field and a positive or 46 * negative `nanos` field. For durations of one second or more, a non-zero value for the 47 * `nanos` field must be of the same sign as the `seconds` field. Must be from -999,999,999 to 48 * +999,999,999 inclusive. 49 * @return new {@code Duration} with specified fields. 50 * @throws IllegalArgumentException if the arguments are out of range or have inconsistent sign. 51 * @since 0.5 52 */ create(long seconds, int nanos)53 public static Duration create(long seconds, int nanos) { 54 if (seconds < -MAX_SECONDS) { 55 throw new IllegalArgumentException( 56 "'seconds' is less than minimum (" + -MAX_SECONDS + "): " + seconds); 57 } 58 if (seconds > MAX_SECONDS) { 59 throw new IllegalArgumentException( 60 "'seconds' is greater than maximum (" + MAX_SECONDS + "): " + seconds); 61 } 62 if (nanos < -MAX_NANOS) { 63 throw new IllegalArgumentException( 64 "'nanos' is less than minimum (" + -MAX_NANOS + "): " + nanos); 65 } 66 if (nanos > MAX_NANOS) { 67 throw new IllegalArgumentException( 68 "'nanos' is greater than maximum (" + MAX_NANOS + "): " + nanos); 69 } 70 if ((seconds < 0 && nanos > 0) || (seconds > 0 && nanos < 0)) { 71 throw new IllegalArgumentException( 72 "'seconds' and 'nanos' have inconsistent sign: seconds=" + seconds + ", nanos=" + nanos); 73 } 74 return new AutoValue_Duration(seconds, nanos); 75 } 76 77 /** 78 * Creates a new {@code Duration} from given milliseconds. 79 * 80 * @param millis the duration in milliseconds. 81 * @return a new {@code Duration} from given milliseconds. 82 * @throws IllegalArgumentException if the number of milliseconds is out of the range that can be 83 * represented by {@code Duration}. 84 * @since 0.5 85 */ fromMillis(long millis)86 public static Duration fromMillis(long millis) { 87 long seconds = millis / MILLIS_PER_SECOND; 88 int nanos = (int) (millis % MILLIS_PER_SECOND * NANOS_PER_MILLI); 89 return Duration.create(seconds, nanos); 90 } 91 92 /** 93 * Converts a {@link Duration} to milliseconds. 94 * 95 * @return the milliseconds representation of this {@code Duration}. 96 * @since 0.13 97 */ toMillis()98 public long toMillis() { 99 return TimeUnit.SECONDS.toMillis(getSeconds()) + TimeUnit.NANOSECONDS.toMillis(getNanos()); 100 } 101 102 /** 103 * Returns the number of seconds in the {@code Duration}. 104 * 105 * @return the number of seconds in the {@code Duration}. 106 * @since 0.5 107 */ getSeconds()108 public abstract long getSeconds(); 109 110 /** 111 * Returns the number of nanoseconds in the {@code Duration}. 112 * 113 * @return the number of nanoseconds in the {@code Duration}. 114 * @since 0.5 115 */ getNanos()116 public abstract int getNanos(); 117 118 /** 119 * Compares this {@code Duration} to the specified {@code Duration}. 120 * 121 * @param otherDuration the other {@code Duration} to compare to, not {@code null}. 122 * @return the comparator value: zero if equal, negative if this duration is smaller than 123 * otherDuration, positive if larger. 124 * @throws NullPointerException if otherDuration is {@code null}. 125 */ 126 @Override compareTo(Duration otherDuration)127 public int compareTo(Duration otherDuration) { 128 int cmp = TimeUtils.compareLongs(getSeconds(), otherDuration.getSeconds()); 129 if (cmp != 0) { 130 return cmp; 131 } 132 return TimeUtils.compareLongs(getNanos(), otherDuration.getNanos()); 133 } 134 Duration()135 Duration() {} 136 } 137