Ticker

Kotlin |Java

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 functions
`Duration!`	`@RequiresApi(api = Build.VERSION_CODES.O) durationBetween(start: Ticks!, end: Ticks!)` Calculates the duration between two `Ticks`.
`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.
`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.
`Long`	`millisBetween(start: Ticks!, end: Ticks!)` Calculates the duration in milliseconds between two `Ticks`.
`Ticks!`	`ticks()` Returns a reading from the clock in ticks.
`Ticks!`	`ticksForElapsedRealtimeMillis(elapsedRealtimeMillis: Long)` 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.
`Ticks!`	`ticksForElapsedRealtimeNanos(elapsedRealtimeNanos: Long)` 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 functions

durationBetween

@RequiresApi(api = Build.VERSION_CODES.O)
fun durationBetween(start: Ticks!, end: Ticks!): Duration!

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
`start: Ticks!`	the start ticks, not null
`end: Ticks!`	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

fun elapsedRealtimeMillisForTicks(ticks: Ticks!): Long

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

fun elapsedRealtimeNanosForTicks(ticks: Ticks!): Long

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

fun millisBetween(start: Ticks!, end: Ticks!): Long

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
`start: Ticks!`	the start ticks, not null
`end: Ticks!`	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

fun ticks(): Ticks!

Returns a reading from the clock in ticks.

ticksForElapsedRealtimeMillis

fun ticksForElapsedRealtimeMillis(elapsedRealtimeMillis: Long): Ticks!

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

fun ticksForElapsedRealtimeNanos(elapsedRealtimeNanos: Long): Ticks!

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.