Ticker
public interface Ticker
Ticker is an abstraction for a clock that can be used to track elapsed time. A Ticker returns unit-less readings from the clock as Ticks. Callers can use Ticks to derive elapsed times in seconds without knowing details of the underlying clock, such as its precision, resolution, and whether it can be reset or has monotonic behavior.
The definition of a second, and therefore the meaning of Duration return values and parameters can vary slightly depending on the ticker's implementation. For example, a Ticker backed by a raw oscillator will usually return "physical seconds" measured by ticks of the oscillator unless it is estimating/adjusting for clock accuracy errors. If another Ticker were tracking Unix epoch seconds, then the length of a second might not always be fixed due to leap second handling.
Some methods declared on this class refer to the elapsed realtime clock. These allow comparisons with values obtained from methods like SystemClock.elapsedRealtime().
Public implementation classes and methods returning Ticker implementations should be clear about the clock behavior.
Summary
Public methods |
|
|---|---|
default Duration |
@RequiresApi(api = Build.VERSION_CODES.O)Calculates the duration between two |
abstract long |
Calculates an elapsed realtime clock value in milliseconds from the supplied |
abstract long |
Calculates an elapsed realtime clock value in nanoseconds from the supplied |
abstract long |
millisBetween(Ticks start, Ticks end)Calculates the duration in milliseconds between two |
abstract Ticks |
ticks()Returns a reading from the clock in ticks. |
abstract Ticks |
ticksForElapsedRealtimeMillis(long elapsedRealtimeMillis)Creates a |
abstract Ticks |
ticksForElapsedRealtimeNanos(long elapsedRealtimeNanos)Creates a |
Public methods
durationBetween
@RequiresApi(api = Build.VERSION_CODES.O)
default Duration durationBetween(Ticks start, Ticks end)
Calculates the duration between two Ticks.
The accuracy and precision of the Duration will depend on the accuracy and precision of the origin Ticker. If the ticks do not originate from this ticker, then an IllegalArgumentException is thrown.
The default implementation delegates to millisBetween.
| Returns | |
|---|---|
Duration |
a non null |
| Throws | |
|---|---|
java.lang.IllegalArgumentException |
if the ticks do not originate from this ticker |
java.lang.ArithmeticException |
if the calculation results in an overflow |
elapsedRealtimeMillisForTicks
abstract long elapsedRealtimeMillisForTicks(Ticks ticks)
Calculates an elapsed realtime clock value in milliseconds from the supplied Ticks, or throws UnsupportedOperationException if the ticker implementation isn't able to convert to elapsed realtime values.
See elapsedRealtimeNanosForTicks for details.
elapsedRealtimeNanosForTicks
abstract long elapsedRealtimeNanosForTicks(Ticks ticks)
Calculates an elapsed realtime clock value in nanoseconds from the supplied Ticks, or throws UnsupportedOperationException if the ticker implementation isn't able to convert to elapsed realtime values.
The Ticker may use a different underlying clock than the device's elapsed realtime nanos clock, or it may adjust for known frequency error in the elapsed realtime clock, so the elapsed realtime clock value returned may only be an approximation. Ordering between returned values from two Ticks depend on the precision of the Ticker implementation.
This method is useful to bridge between code that uses SystemClock.elapsedRealtimeNanos() and similar methods, and code that uses Ticks or Ticker. For example, if code requires an elapsed realtime clock value and it has a Ticks.
millisBetween
abstract long millisBetween(Ticks start, Ticks end)
Calculates the duration in milliseconds between two Ticks.
The accuracy and precision of the duration will depend on the accuracy and precision of the origin Ticker. If the ticks do not originate from this ticker, then an IllegalArgumentException is thrown.
| Returns | |
|---|---|
long |
a long that is the period of time between the two ticks in milliseconds. If |
| Throws | |
|---|---|
java.lang.IllegalArgumentException |
if the ticks do not originate from this ticker |
java.lang.ArithmeticException |
if the calculation results in an overflow |
ticksForElapsedRealtimeMillis
abstract Ticks ticksForElapsedRealtimeMillis(long elapsedRealtimeMillis)
Creates a Ticks from a value supplied by the device's elapsed realtime millis clock, or throws UnsupportedOperationException if the ticker implementation isn't able to convert elapsed realtime values.
See ticksForElapsedRealtimeNanos for details.
ticksForElapsedRealtimeNanos
abstract Ticks ticksForElapsedRealtimeNanos(long elapsedRealtimeNanos)
Creates a Ticks from a value supplied by the device's elapsed realtime nanos clock, or throws UnsupportedOperationException if the ticker implementation isn't able to convert elapsed realtime values.
The Ticker may use a different underlying clock than the device's elapsed realtime clock, or it may adjust for known frequency error in the elapsed realtime clock, so the Ticks returned may only be an approximation. Ordering between Ticks and other properties of the returned Ticks depend on the precision of the Ticker implementation.
This method is useful to bridge between code that uses SystemClock.elapsedRealtimeNanos() and similar methods, and code that uses Ticks or Ticker. For example, if code has a location with an elapsed realtime clock timestamp, the timestamp can be converted to a Ticks using this method and then code like locationTicks.durationUntil(ticker.ticks()) can be used to determine approximately how old it is according to the ticker.