|
| 1 | +package io.sentry.time; |
| 2 | + |
| 3 | +import org.jetbrains.annotations.ApiStatus; |
| 4 | +import org.jetbrains.annotations.NotNull; |
| 5 | + |
| 6 | +/** |
| 7 | + * One wall-clock reading pinned to one monotonic tick, from which related instants are projected. |
| 8 | + * |
| 9 | + * <p>Exists because a group of instants that will be compared against each other — the spans of a |
| 10 | + * transaction, the samples of a profile chunk, the frames of a replay segment — must not each read |
| 11 | + * the wall clock. Two independent readings differ by whatever the device's clock did in between, so |
| 12 | + * a duration taken across them can shorten, lengthen or go negative, and a child can appear to |
| 13 | + * start before its parent. Reading the epoch once and projecting the rest through {@link |
| 14 | + * MonotonicTicker} makes every instant an image of the same tick, so subtracting any two of them |
| 15 | + * reports measured time. The span protocol needs exactly that: it carries a start and an end |
| 16 | + * instant and no duration field, so the server subtracts them. |
| 17 | + * |
| 18 | + * <p>Projection also buys resolution the wall clock does not have: on Android the epoch is |
| 19 | + * millisecond-granular, so an instant read directly is truncated, whereas one projected from a tick |
| 20 | + * carries nanoseconds. That is the workaround {@link io.sentry.SentryNanotimeDate} describes, |
| 21 | + * applied once per group rather than to every reading. OpenTelemetry's SDK anchors per local root |
| 22 | + * span for the same two reasons. |
| 23 | + * |
| 24 | + * <p>The cost is that a projection ages: it reports what the wall clock said when the anchor was |
| 25 | + * taken plus the time measured since, so a later correction to the device's clock — an NTP sync, or |
| 26 | + * the user setting the time — never reaches it. Anchor something short-lived. |
| 27 | + */ |
| 28 | +@ApiStatus.Internal |
| 29 | +public final class AnchoredClock { |
| 30 | + |
| 31 | + private final @NotNull MonotonicTicker ticker; |
| 32 | + private final long epochNanos; |
| 33 | + private final long anchorTick; |
| 34 | + |
| 35 | + private AnchoredClock( |
| 36 | + final @NotNull MonotonicTicker ticker, final long epochNanos, final long anchorTick) { |
| 37 | + this.ticker = ticker; |
| 38 | + this.epochNanos = epochNanos; |
| 39 | + this.anchorTick = anchorTick; |
| 40 | + } |
| 41 | + |
| 42 | + /** Takes the anchor now: one epoch reading, one tick, as close together as a call allows. */ |
| 43 | + public static @NotNull AnchoredClock create( |
| 44 | + final @NotNull EpochClock epoch, final @NotNull MonotonicTicker ticker) { |
| 45 | + return new AnchoredClock(ticker, epoch.now().epochNanos(), ticker.tickNanos()); |
| 46 | + } |
| 47 | + |
| 48 | + /** |
| 49 | + * The instant the anchor was taken — the one instant here that was read rather than projected. |
| 50 | + * |
| 51 | + * <p>Reads no clock and never changes. Every other instant this class returns is this one plus |
| 52 | + * measured time. |
| 53 | + */ |
| 54 | + public @NotNull Timestamp origin() { |
| 55 | + return Timestamp.anchoredAt(epochNanos, this); |
| 56 | + } |
| 57 | + |
| 58 | + /** The current instant: {@link #origin()} plus the time the ticker has measured since. */ |
| 59 | + public @NotNull Timestamp now() { |
| 60 | + return at(ticker.tickNanos()); |
| 61 | + } |
| 62 | + |
| 63 | + /** |
| 64 | + * The instant a tick corresponds to, for placing something already measured on this ticker — a |
| 65 | + * frame, a profiler sample — on the same timeline as the instants projected here. |
| 66 | + */ |
| 67 | + public @NotNull Timestamp at(final long tickNanos) { |
| 68 | + return Timestamp.anchoredAt(epochNanos + (tickNanos - anchorTick), this); |
| 69 | + } |
| 70 | + |
| 71 | + /** |
| 72 | + * The tick an instant was projected from. Exact, and reads no clock: projection adds a tick |
| 73 | + * difference to a fixed epoch, so subtraction inverts it. |
| 74 | + * |
| 75 | + * @throws IllegalArgumentException if this clock did not project the instant. Its epoch bears no |
| 76 | + * arithmetic relation to these ticks, so converting it would silently produce a tick derived |
| 77 | + * from a wall-clock difference. |
| 78 | + */ |
| 79 | + public long tickOf(final @NotNull Timestamp timestamp) { |
| 80 | + if (timestamp.anchor() != this) { |
| 81 | + throw new IllegalArgumentException( |
| 82 | + "Timestamp was not projected by this AnchoredClock: " + timestamp); |
| 83 | + } |
| 84 | + return anchorTick + (timestamp.epochNanos() - epochNanos); |
| 85 | + } |
| 86 | +} |
0 commit comments