Ticker

Kotlin |Java

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) durationBetween(Ticks start, Ticks end)` Calculates the duration between two `Ticks`.
`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.
`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.
`abstract long`	`millisBetween(Ticks start, Ticks end)` Calculates the duration in milliseconds between two `Ticks`.
`abstract Ticks`	`ticks()` Returns a reading from the clock in ticks.
`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.
`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.

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.

Parameters
`Ticks start`	the start ticks, not null
`Ticks end`	the end ticks, not null

Returns
`Duration`	a non null `Duration` that is the period of time between the two ticks. If `start` was read after `end` then the return value will be a negative period; else it is positive.

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.

Parameters
`Ticks start`	the start ticks, not null
`Ticks end`	the end ticks, not null

Returns
`long`	a long that is the period of time between the two ticks in milliseconds. If `start` was read after `end` then the return value will be a negative period else it is positive.

Throws
`java.lang.IllegalArgumentException`	if the ticks do not originate from this ticker
`java.lang.ArithmeticException`	if the calculation results in an overflow

ticks

abstract Ticks ticks()

Returns a reading from the clock in ticks.

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.