TimeSignal
public interface TimeSignal
TimeSignal represents a time synchronization transaction with an external clock. It encapsulates an instant according to the external clock, the information needed to account for the time taken to obtain the signal, and the time elapsed locally since that instant was received. Accuracy metadata needed to estimate probable error is also included.
Warning: Users should keep in mind that using the same time signal indefinitely will lead to greater and greater errors due to local clock inaccuracies. Time signals should be refreshed periodically using methods like addTimeSignalListener and getLatestTimeSignal.
Summary
Public methods |
|
|---|---|
abstract @Nullable ComputedInstant |
Computes the current Unix epoch time from this time signal as a |
abstract @Nullable ComputedInstant |
computeInstantAt(Ticks ticks)Computes the Unix epoch time from this time signal at |
abstract Duration |
@RequiresApi(api = Build.VERSION_CODES.O)Returns an absolute accuracy estimate for this time signal as a |
abstract long |
Returns an absolute accuracy estimate for this time signal in milliseconds. |
abstract Ticks |
Returns the |
Public methods
computeCurrentInstant
abstract @Nullable ComputedInstant computeCurrentInstant()
Computes the current Unix epoch time from this time signal as a ComputedInstant. The method may return null once we introduce the ability to specify accuracy constraints via future APIs.
The value is computed by adjusting for the time elapsed between when this time signal was acquired and now. Accuracy of the result is affected by the magnitude of difference between the time now and when the time signal was acquired.
| Throws | |
|---|---|
java.lang.ArithmeticException |
if numeric overflow occurs |
computeInstantAt
abstract @Nullable ComputedInstant computeInstantAt(Ticks ticks)
Computes the Unix epoch time from this time signal at ticks as a ComputedInstant. The method may return null once we introduce the ability to specify accuracy constraints via future APIs.
The value is computed by adjusting for the time elapsed between when this time signal was acquired and ticks. Accuracy of the result is affected by the magnitude of difference between ticks and when the time signal was acquired.
ticks can be from before this time signal was acquired.
| Throws | |
|---|---|
java.lang.IllegalArgumentException |
if the supplied |
java.lang.ArithmeticException |
if numeric overflow occurs |
getAcquisitionEstimatedError
@RequiresApi(api = Build.VERSION_CODES.O)
abstract Duration getAcquisitionEstimatedError()
Returns an absolute accuracy estimate for this time signal as a Duration.
This value encapsulates error accumulated up to the acquisition of the time signal. For example, for a time signal received over a network connection the estimated error will include information about the error that might have been introduced by asymmetric network latency. It may also include information transmitted from the remote source about its own accumulated error quantity. These values are only estimates and can be used to compare quality of two time signals from the same source. As an estimate, the actual error could be larger. See computeCurrentInstant for a method that produces a result incorporates this information and accounts for additional source of errors that may be introduced by local ticker inaccuracy and time signal age.
getAcquisitionEstimatedErrorMillis
abstract long getAcquisitionEstimatedErrorMillis()
Returns an absolute accuracy estimate for this time signal in milliseconds.
This value encapsulates error accumulated up to the acquisition of the time signal. For example, for a time signal received over a network connection the estimated error will include information about the error that might have been introduced by asymmetric network latency. It may also include information transmitted from the remote source about its own accumulated error quantity. These values are only estimates and can be used to compare quality of two time signals from the same source. As an estimate, the actual error could be larger. See computeCurrentInstant for a method that produces a result incorporates this information and accounts for additional source of errors that may be introduced by local ticker inaccuracy and time signal age.
getAcquisitionTicks
abstract Ticks getAcquisitionTicks()
Returns the Ticks when the time signal was acquired.
This Ticks can be used to age this time signal or to compare with other time signals.