Skip to content

Commit d7bc897

Browse files
committed
ref(time): Rename MonotonicClock to MonotonicTicker (JAVA-571)
The type promises less than "clock" suggests: a tick carries no unit and no epoch, and only differences between two ticks from the same instance mean anything. "Ticker" keeps it from reading like a source of wall-clock time. Deadline.after now rejects a negative amount, since a deadline that starts out in the past is a sign error at the call site and passed() already expresses that case deliberately. Also drops the "state that has not been populated yet" framing from the Deadline.passed javadoc, covers isAfter on two equal deadlines, and rewrites the tick-zero test comment to name the last-updated-timestamp pattern it is about, rather than leaving "sentinel of 0" to be read as a deadline of 0.
1 parent d27758d commit d7bc897

14 files changed

Lines changed: 136 additions & 115 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@
1010

1111
### Internal
1212

13-
- Add an internal `MonotonicClock` abstraction with `Deadline` and `Stopwatch` primitives ([#6028](https://github.com/getsentry/sentry-java/pull/6028))
13+
- Add an internal `MonotonicTicker` abstraction with `Deadline` and `Stopwatch` primitives ([#6028](https://github.com/getsentry/sentry-java/pull/6028))
1414

1515
## 8.55.0
1616

‎sentry-android-core/api/sentry-android-core.api‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -414,7 +414,7 @@ public final class io/sentry/android/core/SentryAndroidOptions : io/sentry/Sentr
414414
public fun getBeforeViewHierarchyCaptureCallback ()Lio/sentry/android/core/SentryAndroidOptions$BeforeCaptureCallback;
415415
public fun getDebugImagesLoader ()Lio/sentry/android/core/IDebugImagesLoader;
416416
public fun getFrameMetricsCollector ()Lio/sentry/android/core/internal/util/SentryFrameMetricsCollector;
417-
public fun getMonotonicClock ()Lio/sentry/time/MonotonicClock;
417+
public fun getMonotonicTicker ()Lio/sentry/time/MonotonicTicker;
418418
public fun getNativeSdkName ()Ljava/lang/String;
419419
public fun getNdkAppHangTimeoutIntervalMillis ()J
420420
public fun getNdkHandlerStrategy ()I

‎sentry-android-core/src/main/java/io/sentry/android/core/SentryAndroidOptions.java‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -12,13 +12,13 @@
1212
import io.sentry.SentryLevel;
1313
import io.sentry.SentryOptions;
1414
import io.sentry.SpanStatus;
15-
import io.sentry.android.core.internal.time.AndroidMonotonicClock;
15+
import io.sentry.android.core.internal.time.AndroidMonotonicTicker;
1616
import io.sentry.android.core.internal.util.RootChecker;
1717
import io.sentry.android.core.internal.util.SentryFrameMetricsCollector;
1818
import io.sentry.protocol.Mechanism;
1919
import io.sentry.protocol.SdkVersion;
2020
import io.sentry.protocol.SentryId;
21-
import io.sentry.time.MonotonicClock;
21+
import io.sentry.time.MonotonicTicker;
2222
import io.sentry.util.SampleRateUtils;
2323
import org.jetbrains.annotations.ApiStatus;
2424
import org.jetbrains.annotations.NotNull;
@@ -893,8 +893,8 @@ public void setEnableAnrFingerprinting(final boolean enableAnrFingerprinting) {
893893

894894
@Override
895895
@ApiStatus.Internal
896-
public @NotNull MonotonicClock getMonotonicClock() {
897-
return AndroidMonotonicClock.getInstance();
896+
public @NotNull MonotonicTicker getMonotonicTicker() {
897+
return AndroidMonotonicTicker.getInstance();
898898
}
899899

900900
static class AndroidUserFeedbackFormHandler implements SentryFeedbackOptions.IFormHandler {

sentry-android-core/src/main/java/io/sentry/android/core/internal/time/AndroidMonotonicClock.java renamed to sentry-android-core/src/main/java/io/sentry/android/core/internal/time/AndroidMonotonicTicker.java

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,26 +1,26 @@
11
package io.sentry.android.core.internal.time;
22

33
import android.os.SystemClock;
4-
import io.sentry.time.MonotonicClock;
4+
import io.sentry.time.MonotonicTicker;
55
import org.jetbrains.annotations.ApiStatus;
66
import org.jetbrains.annotations.NotNull;
77

88
/**
9-
* {@link MonotonicClock} backed by {@link SystemClock#elapsedRealtimeNanos()}.
9+
* {@link MonotonicTicker} backed by {@link SystemClock#elapsedRealtimeNanos()}.
1010
*
1111
* <p>That is {@code CLOCK_BOOTTIME}, so it keeps counting while the device is suspended — unlike
1212
* {@link System#nanoTime()}, which the core module falls back to and which stops in deep sleep.
1313
*/
1414
@ApiStatus.Internal
15-
public final class AndroidMonotonicClock implements MonotonicClock {
15+
public final class AndroidMonotonicTicker implements MonotonicTicker {
1616

17-
private static final AndroidMonotonicClock instance = new AndroidMonotonicClock();
17+
private static final AndroidMonotonicTicker instance = new AndroidMonotonicTicker();
1818

19-
public static @NotNull MonotonicClock getInstance() {
19+
public static @NotNull MonotonicTicker getInstance() {
2020
return instance;
2121
}
2222

23-
private AndroidMonotonicClock() {}
23+
private AndroidMonotonicTicker() {}
2424

2525
@Override
2626
public long tickNanos() {

sentry-test-support/src/main/kotlin/io/sentry/time/TestMonotonicClock.kt renamed to sentry-test-support/src/main/kotlin/io/sentry/time/TestMonotonicTicker.kt

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -3,13 +3,13 @@ package io.sentry.time
33
import java.util.concurrent.TimeUnit
44

55
/**
6-
* A [MonotonicClock] that only moves when a test tells it to.
6+
* A [MonotonicTicker] that only moves when a test tells it to.
77
*
88
* Advancing by an amount *and a unit* is the point: a stubbed `thenReturn(1001)` against a
9-
* nanosecond clock is off by a factor of a million and still compiles, whereas `advance(1001,
9+
* nanosecond ticker is off by a factor of a million and still compiles, whereas `advance(1001,
1010
* MILLISECONDS)` cannot be.
1111
*/
12-
class TestMonotonicClock(private var nanos: Long = 0) : MonotonicClock {
12+
class TestMonotonicTicker(private var nanos: Long = 0) : MonotonicTicker {
1313
override fun tickNanos(): Long = nanos
1414

1515
fun advance(amount: Long, unit: TimeUnit) {

‎sentry/api/sentry.api‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -3740,7 +3740,7 @@ public class io/sentry/SentryOptions {
37403740
public fun getMaxTraceFileSize ()J
37413741
public fun getMetrics ()Lio/sentry/SentryOptions$Metrics;
37423742
public fun getModulesLoader ()Lio/sentry/internal/modules/IModulesLoader;
3743-
public fun getMonotonicClock ()Lio/sentry/time/MonotonicClock;
3743+
public fun getMonotonicTicker ()Lio/sentry/time/MonotonicTicker;
37443744
public fun getOnDiscard ()Lio/sentry/SentryOptions$OnDiscardCallback;
37453745
public fun getOnOversizedEvent ()Lio/sentry/SentryOptions$OnOversizedEventCallback;
37463746
public fun getOpenTelemetryMode ()Lio/sentry/SentryOpenTelemetryMode;
@@ -7599,26 +7599,26 @@ public final class io/sentry/rrweb/RRWebVideoEvent$JsonKeys {
75997599
}
76007600

76017601
public final class io/sentry/time/Deadline {
7602-
public static fun after (Lio/sentry/time/MonotonicClock;JLjava/util/concurrent/TimeUnit;)Lio/sentry/time/Deadline;
7602+
public static fun after (Lio/sentry/time/MonotonicTicker;JLjava/util/concurrent/TimeUnit;)Lio/sentry/time/Deadline;
76037603
public fun hasPassed ()Z
76047604
public fun isAfter (Lio/sentry/time/Deadline;)Z
7605-
public static fun passed (Lio/sentry/time/MonotonicClock;)Lio/sentry/time/Deadline;
7605+
public static fun passed (Lio/sentry/time/MonotonicTicker;)Lio/sentry/time/Deadline;
76067606
public fun remaining (Ljava/util/concurrent/TimeUnit;)J
76077607
}
76087608

7609-
public final class io/sentry/time/JavaMonotonicClock : io/sentry/time/MonotonicClock {
7610-
public static fun getInstance ()Lio/sentry/time/MonotonicClock;
7609+
public final class io/sentry/time/JavaMonotonicTicker : io/sentry/time/MonotonicTicker {
7610+
public static fun getInstance ()Lio/sentry/time/MonotonicTicker;
76117611
public fun tickNanos ()J
76127612
}
76137613

7614-
public abstract interface class io/sentry/time/MonotonicClock {
7614+
public abstract interface class io/sentry/time/MonotonicTicker {
76157615
public abstract fun tickNanos ()J
76167616
}
76177617

76187618
public final class io/sentry/time/Stopwatch {
76197619
public fun elapsed (Ljava/util/concurrent/TimeUnit;)J
76207620
public fun elapsedNanos ()J
7621-
public static fun started (Lio/sentry/time/MonotonicClock;)Lio/sentry/time/Stopwatch;
7621+
public static fun started (Lio/sentry/time/MonotonicTicker;)Lio/sentry/time/Stopwatch;
76227622
}
76237623

76247624
public final class io/sentry/transport/AsyncHttpTransport : io/sentry/transport/ITransport {

‎sentry/src/main/java/io/sentry/SentryOptions.java‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -21,8 +21,8 @@
2121
import io.sentry.metrics.IMetricsBatchProcessorFactory;
2222
import io.sentry.protocol.SdkVersion;
2323
import io.sentry.protocol.SentryTransaction;
24-
import io.sentry.time.JavaMonotonicClock;
25-
import io.sentry.time.MonotonicClock;
24+
import io.sentry.time.JavaMonotonicTicker;
25+
import io.sentry.time.MonotonicTicker;
2626
import io.sentry.transport.ITransport;
2727
import io.sentry.transport.ITransportGate;
2828
import io.sentry.transport.NoOpEnvelopeCache;
@@ -3062,15 +3062,15 @@ public void setDateProvider(final @NotNull SentryDateProvider dateProvider) {
30623062
}
30633063

30643064
/**
3065-
* Returns the clock used to measure elapsed time, such as rate-limit windows, cache expiry and
3065+
* Returns the ticker used to measure elapsed time, such as rate-limit windows, cache expiry and
30663066
* ANR thresholds.
30673067
*
3068-
* <p>Android overrides this with a {@code SystemClock.elapsedRealtimeNanos()}-backed clock, which
3069-
* this module cannot reference. On the JVM there is no suspend state to account for.
3068+
* <p>Android overrides this with a {@code SystemClock.elapsedRealtimeNanos()}-backed ticker,
3069+
* which this module cannot reference. On the JVM there is no suspend state to account for.
30703070
*/
30713071
@ApiStatus.Internal
3072-
public @NotNull MonotonicClock getMonotonicClock() {
3073-
return JavaMonotonicClock.getInstance();
3072+
public @NotNull MonotonicTicker getMonotonicTicker() {
3073+
return JavaMonotonicTicker.getInstance();
30743074
}
30753075

30763076
/**

‎sentry/src/main/java/io/sentry/time/Deadline.java‎

Lines changed: 29 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
import org.jetbrains.annotations.NotNull;
66

77
/**
8-
* A point in the future, measured on a {@link MonotonicClock}.
8+
* A point in the future, measured on a {@link MonotonicTicker}.
99
*
1010
* <p>Exists so that callers never do arithmetic on raw ticks. A tick carries no unit and no epoch,
1111
* so spelling out {@code now - then < ttl} at every call site is where unit mix-ups, sentinels that
@@ -15,32 +15,42 @@
1515
@ApiStatus.Internal
1616
public final class Deadline {
1717

18-
private final @NotNull MonotonicClock clock;
18+
private final @NotNull MonotonicTicker ticker;
1919
private final long deadlineNanos;
2020

21-
private Deadline(final @NotNull MonotonicClock clock, final long deadlineNanos) {
22-
this.clock = clock;
21+
private Deadline(final @NotNull MonotonicTicker ticker, final long deadlineNanos) {
22+
this.ticker = ticker;
2323
this.deadlineNanos = deadlineNanos;
2424
}
2525

26-
/** A deadline {@code amount} of {@code unit} from now. */
26+
/**
27+
* A deadline {@code amount} of {@code unit} from now.
28+
*
29+
* @throws IllegalArgumentException if {@code amount} is negative. A deadline that starts out in
30+
* the past is a sign error at the call site; {@link #passed} says it deliberately.
31+
*/
2732
public static @NotNull Deadline after(
28-
final @NotNull MonotonicClock clock, final long amount, final @NotNull TimeUnit unit) {
29-
return new Deadline(clock, clock.tickNanos() + unit.toNanos(amount));
33+
final @NotNull MonotonicTicker ticker, final long amount, final @NotNull TimeUnit unit) {
34+
if (amount < 0) {
35+
throw new IllegalArgumentException("Deadline amount must not be negative, but was " + amount);
36+
}
37+
return new Deadline(ticker, ticker.tickNanos() + unit.toNanos(amount));
3038
}
3139

3240
/**
33-
* A deadline that has already passed. Use for state that has not been populated yet, so that
34-
* "never set" needs no numeric sentinel and cannot be mistaken for fresh — {@code 0} is a real
35-
* and very recent instant on any boot-relative clock.
41+
* A deadline that has already passed.
42+
*
43+
* <p>Saves callers from reserving a tick value to mean "not set yet": {@code 0} is a real and
44+
* very recent instant on a boot-relative ticker, so a field left at {@code 0} reads as freshly
45+
* set rather than as unset.
3646
*/
37-
public static @NotNull Deadline passed(final @NotNull MonotonicClock clock) {
38-
return new Deadline(clock, clock.tickNanos());
47+
public static @NotNull Deadline passed(final @NotNull MonotonicTicker ticker) {
48+
return new Deadline(ticker, ticker.tickNanos());
3949
}
4050

4151
public boolean hasPassed() {
4252
// Subtraction rather than `<`: a tick origin is arbitrary, may be negative, and may wrap.
43-
return clock.tickNanos() - deadlineNanos >= 0;
53+
return ticker.tickNanos() - deadlineNanos >= 0;
4454
}
4555

4656
/**
@@ -51,7 +61,7 @@ public boolean hasPassed() {
5161
* standing.
5262
*/
5363
public long remaining(final @NotNull TimeUnit unit) {
54-
final long remainingNanos = deadlineNanos - clock.tickNanos();
64+
final long remainingNanos = deadlineNanos - ticker.tickNanos();
5565
if (remainingNanos <= 0) {
5666
return 0;
5767
}
@@ -63,16 +73,16 @@ public long remaining(final @NotNull TimeUnit unit) {
6373
/**
6474
* Whether this deadline falls after {@code other}.
6575
*
66-
* @throws IllegalArgumentException if the two were created from different clocks, whose origins
76+
* @throws IllegalArgumentException if the two were created from different tickers, whose origins
6777
* are unrelated and whose ticks are therefore not comparable.
6878
*/
6979
public boolean isAfter(final @NotNull Deadline other) {
70-
if (clock != other.clock) {
80+
if (ticker != other.ticker) {
7181
throw new IllegalArgumentException(
72-
"Cannot compare deadlines from different clocks: "
73-
+ clock.getClass().getName()
82+
"Cannot compare deadlines from different tickers: "
83+
+ ticker.getClass().getName()
7484
+ " and "
75-
+ other.clock.getClass().getName());
85+
+ other.ticker.getClass().getName());
7686
}
7787
return deadlineNanos - other.deadlineNanos > 0;
7888
}

‎sentry/src/main/java/io/sentry/time/JavaMonotonicClock.java‎

Lines changed: 0 additions & 22 deletions
This file was deleted.
Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
package io.sentry.time;
2+
3+
import org.jetbrains.annotations.ApiStatus;
4+
import org.jetbrains.annotations.NotNull;
5+
6+
/** {@link MonotonicTicker} backed by {@link System#nanoTime()}. */
7+
@ApiStatus.Internal
8+
public final class JavaMonotonicTicker implements MonotonicTicker {
9+
10+
private static final JavaMonotonicTicker instance = new JavaMonotonicTicker();
11+
12+
public static @NotNull MonotonicTicker getInstance() {
13+
return instance;
14+
}
15+
16+
private JavaMonotonicTicker() {}
17+
18+
@Override
19+
public long tickNanos() {
20+
return System.nanoTime();
21+
}
22+
}

0 commit comments

Comments
 (0)