feat(time): Add a monotonic clock abstraction (JAVA-571)

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## Unreleased
+
+### Internal
+
+- Add an internal `MonotonicClock` abstraction with `Deadline` and `Stopwatch` primitives ([#6028](https://github.com/getsentry/sentry-java/pull/6028))
+
 ## 8.55.0
 
 ### Features

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

@@ -414,6 +414,7 @@ public final class io/sentry/android/core/SentryAndroidOptions : io/sentry/Sentr
 	public fun getBeforeViewHierarchyCaptureCallback ()Lio/sentry/android/core/SentryAndroidOptions$BeforeCaptureCallback;
 	public fun getDebugImagesLoader ()Lio/sentry/android/core/IDebugImagesLoader;
 	public fun getFrameMetricsCollector ()Lio/sentry/android/core/internal/util/SentryFrameMetricsCollector;
+	public fun getMonotonicClock ()Lio/sentry/time/MonotonicClock;
 	public fun getNativeSdkName ()Ljava/lang/String;
 	public fun getNdkAppHangTimeoutIntervalMillis ()J
 	public fun getNdkHandlerStrategy ()I

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

@@ -12,11 +12,13 @@
 import io.sentry.SentryLevel;
 import io.sentry.SentryOptions;
 import io.sentry.SpanStatus;
+import io.sentry.android.core.internal.time.AndroidMonotonicClock;
 import io.sentry.android.core.internal.util.RootChecker;
 import io.sentry.android.core.internal.util.SentryFrameMetricsCollector;
 import io.sentry.protocol.Mechanism;
 import io.sentry.protocol.SdkVersion;
 import io.sentry.protocol.SentryId;
+import io.sentry.time.MonotonicClock;
 import io.sentry.util.SampleRateUtils;
 import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.NotNull;
@@ -889,6 +891,12 @@ public void setEnableAnrFingerprinting(final boolean enableAnrFingerprinting) {
     this.enableAnrFingerprinting = enableAnrFingerprinting;
   }
 
+  @Override
+  @ApiStatus.Internal
+  public @NotNull MonotonicClock getMonotonicClock() {
+    return AndroidMonotonicClock.getInstance();
+  }
+
   static class AndroidUserFeedbackFormHandler implements SentryFeedbackOptions.IFormHandler {
     @Override
     public void showForm(

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

@@ -0,0 +1,29 @@
+package io.sentry.android.core.internal.time;
+
+import android.os.SystemClock;
+import io.sentry.time.MonotonicClock;
+import org.jetbrains.annotations.ApiStatus;
+import org.jetbrains.annotations.NotNull;
+
+/**
+ * {@link MonotonicClock} backed by {@link SystemClock#elapsedRealtimeNanos()}.
+ *
+ * <p>That is {@code CLOCK_BOOTTIME}, so it keeps counting while the device is suspended — unlike
+ * {@link System#nanoTime()}, which the core module falls back to and which stops in deep sleep.
+ */
+@ApiStatus.Internal
+public final class AndroidMonotonicClock implements MonotonicClock {
+
+  private static final AndroidMonotonicClock instance = new AndroidMonotonicClock();
+
+  public static @NotNull MonotonicClock getInstance() {
+    return instance;
+  }
+
+  private AndroidMonotonicClock() {}
+
+  @Override
+  public long tickNanos() {
+    return SystemClock.elapsedRealtimeNanos();
+  }
+}

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

@@ -0,0 +1,18 @@
+package io.sentry.time
+
+import java.util.concurrent.TimeUnit
+
+/**
+ * A [MonotonicClock] that only moves when a test tells it to.
+ *
+ * Advancing by an amount *and a unit* is the point: a stubbed `thenReturn(1001)` against a
+ * nanosecond clock is off by a factor of a million and still compiles, whereas `advance(1001,
+ * MILLISECONDS)` cannot be.
+ */
+class TestMonotonicClock(private var nanos: Long = 0) : MonotonicClock {
+  override fun tickNanos(): Long = nanos
+
+  fun advance(amount: Long, unit: TimeUnit) {
+    nanos += unit.toNanos(amount)
+  }
+}

sentry/api/sentry.api

@@ -3740,6 +3740,7 @@ public class io/sentry/SentryOptions {
 	public fun getMaxTraceFileSize ()J
 	public fun getMetrics ()Lio/sentry/SentryOptions$Metrics;
 	public fun getModulesLoader ()Lio/sentry/internal/modules/IModulesLoader;
+	public fun getMonotonicClock ()Lio/sentry/time/MonotonicClock;
 	public fun getOnDiscard ()Lio/sentry/SentryOptions$OnDiscardCallback;
 	public fun getOnOversizedEvent ()Lio/sentry/SentryOptions$OnOversizedEventCallback;
 	public fun getOpenTelemetryMode ()Lio/sentry/SentryOpenTelemetryMode;
@@ -7597,6 +7598,29 @@ public final class io/sentry/rrweb/RRWebVideoEvent$JsonKeys {
 	public fun <init> ()V
 }
 
+public final class io/sentry/time/Deadline {
+	public static fun after (Lio/sentry/time/MonotonicClock;JLjava/util/concurrent/TimeUnit;)Lio/sentry/time/Deadline;
+	public fun hasPassed ()Z
+	public fun isAfter (Lio/sentry/time/Deadline;)Z
+	public static fun passed (Lio/sentry/time/MonotonicClock;)Lio/sentry/time/Deadline;
+	public fun remaining (Ljava/util/concurrent/TimeUnit;)J
+}
+
+public final class io/sentry/time/JavaMonotonicClock : io/sentry/time/MonotonicClock {
+	public static fun getInstance ()Lio/sentry/time/MonotonicClock;
+	public fun tickNanos ()J
+}
+
+public abstract interface class io/sentry/time/MonotonicClock {
+	public abstract fun tickNanos ()J
+}
+
+public final class io/sentry/time/Stopwatch {
+	public fun elapsed (Ljava/util/concurrent/TimeUnit;)J
+	public fun elapsedNanos ()J
+	public static fun started (Lio/sentry/time/MonotonicClock;)Lio/sentry/time/Stopwatch;
+}
+
 public final class io/sentry/transport/AsyncHttpTransport : io/sentry/transport/ITransport {
 	public fun <init> (Lio/sentry/SentryOptions;Lio/sentry/transport/RateLimiter;Lio/sentry/transport/ITransportGate;Lio/sentry/RequestDetails;)V
 	public fun <init> (Lio/sentry/transport/QueuedThreadPoolExecutor;Lio/sentry/SentryOptions;Lio/sentry/transport/RateLimiter;Lio/sentry/transport/ITransportGate;Lio/sentry/transport/HttpConnection;)V

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

@@ -21,6 +21,8 @@
 import io.sentry.metrics.IMetricsBatchProcessorFactory;
 import io.sentry.protocol.SdkVersion;
 import io.sentry.protocol.SentryTransaction;
+import io.sentry.time.JavaMonotonicClock;
+import io.sentry.time.MonotonicClock;
 import io.sentry.transport.ITransport;
 import io.sentry.transport.ITransportGate;
 import io.sentry.transport.NoOpEnvelopeCache;
@@ -3059,6 +3061,18 @@ public void setDateProvider(final @NotNull SentryDateProvider dateProvider) {
     this.dateProvider.setValue(dateProvider);
   }
 
+  /**
+   * Returns the clock used to measure elapsed time, such as rate-limit windows, cache expiry and
+   * ANR thresholds.
+   *
+   * <p>Android overrides this with a {@code SystemClock.elapsedRealtimeNanos()}-backed clock, which
+   * this module cannot reference. On the JVM there is no suspend state to account for.
+   */
+  @ApiStatus.Internal
+  public @NotNull MonotonicClock getMonotonicClock() {
+    return JavaMonotonicClock.getInstance();
+  }
+
   /**
    * Adds a ICollector.
    *

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

@@ -0,0 +1,79 @@
+package io.sentry.time;
+
+import java.util.concurrent.TimeUnit;
+import org.jetbrains.annotations.ApiStatus;
+import org.jetbrains.annotations.NotNull;
+
+/**
+ * A point in the future, measured on a {@link MonotonicClock}.
+ *
+ * <p>Exists so that callers never do arithmetic on raw ticks. A tick carries no unit and no epoch,
+ * so spelling out {@code now - then < ttl} at every call site is where unit mix-ups, sentinels that
+ * happen to mean "boot", and wrap-unsafe {@code <} comparisons come from. Each of those is decided
+ * once, here.
+ */
+@ApiStatus.Internal
+public final class Deadline {
+
+  private final @NotNull MonotonicClock clock;
+  private final long deadlineNanos;
+
+  private Deadline(final @NotNull MonotonicClock clock, final long deadlineNanos) {
+    this.clock = clock;
+    this.deadlineNanos = deadlineNanos;
+  }
+
+  /** A deadline {@code amount} of {@code unit} from now. */
+  public static @NotNull Deadline after(
+      final @NotNull MonotonicClock clock, final long amount, final @NotNull TimeUnit unit) {
+    return new Deadline(clock, clock.tickNanos() + unit.toNanos(amount));
+  }
+
+  /**
+   * A deadline that has already passed. Use for state that has not been populated yet, so that
+   * "never set" needs no numeric sentinel and cannot be mistaken for fresh — {@code 0} is a real
+   * and very recent instant on any boot-relative clock.
+   */
+  public static @NotNull Deadline passed(final @NotNull MonotonicClock clock) {
+    return new Deadline(clock, clock.tickNanos());
+  }
+
+  public boolean hasPassed() {
+    // Subtraction rather than `<`: a tick origin is arbitrary, may be negative, and may wrap.
+    return clock.tickNanos() - deadlineNanos >= 0;
+  }
+
+  /**
+   * How much time is left, rounded up, or zero once the deadline has passed.
+   *
+   * <p>Rounding up matters: callers schedule work for {@code remaining()} and then re-check {@link
+   * #hasPassed()}. Truncating would wake them a fraction early, to find the deadline still
+   * standing.
+   */
+  public long remaining(final @NotNull TimeUnit unit) {
+    final long remainingNanos = deadlineNanos - clock.tickNanos();
+    if (remainingNanos <= 0) {
+      return 0;
+    }
+    final long unitNanos = unit.toNanos(1);
+    final long whole = remainingNanos / unitNanos;
+    return remainingNanos % unitNanos == 0 ? whole : whole + 1;
+  }
+
+  /**
+   * Whether this deadline falls after {@code other}.
+   *
+   * @throws IllegalArgumentException if the two were created from different clocks, whose origins
+   *     are unrelated and whose ticks are therefore not comparable.
+   */
+  public boolean isAfter(final @NotNull Deadline other) {
+    if (clock != other.clock) {
+      throw new IllegalArgumentException(
+          "Cannot compare deadlines from different clocks: "
+              + clock.getClass().getName()
+              + " and "
+              + other.clock.getClass().getName());
+    }
+    return deadlineNanos - other.deadlineNanos > 0;
+  }
+}

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

@@ -0,0 +1,22 @@
+package io.sentry.time;
+
+import org.jetbrains.annotations.ApiStatus;
+import org.jetbrains.annotations.NotNull;
+
+/** {@link MonotonicClock} backed by {@link System#nanoTime()}. */
+@ApiStatus.Internal
+public final class JavaMonotonicClock implements MonotonicClock {
+
+  private static final JavaMonotonicClock instance = new JavaMonotonicClock();
+
+  public static @NotNull MonotonicClock getInstance() {
+    return instance;
+  }
+
+  private JavaMonotonicClock() {}
+
+  @Override
+  public long tickNanos() {
+    return System.nanoTime();
+  }
+}

sentry/src/main/java/io/sentry/time/MonotonicClock.java

@@ -0,0 +1,22 @@
+package io.sentry.time;
+
+import org.jetbrains.annotations.ApiStatus;
+
+/**
+ * A monotonically increasing nanosecond counter, including time the device spent suspended in deep
+ * sleep.
+ *
+ * <p>This type deliberately promises very little: a tick is a number that does not go backwards,
+ * measured from an origin that is arbitrary and may be negative. Only <em>differences</em> between
+ * two ticks from the same instance are meaningful, and a tick must never be persisted, serialized,
+ * or compared against a value from another clock.
+ *
+ * <p>On Android this is {@code CLOCK_BOOTTIME}, via {@code SystemClock.elapsedRealtimeNanos()}, so
+ * an interval measured across a suspend reports the real time that passed rather than only the time
+ * the CPU was awake. On the JVM there is no comparable suspend state, so {@link System#nanoTime()}
+ * is equivalent.
+ */
+@ApiStatus.Internal
+public interface MonotonicClock {
+  long tickNanos();
+}

sentry/src/main/java/io/sentry/time/Stopwatch.java

@@ -0,0 +1,35 @@
+package io.sentry.time;
+
+import java.util.concurrent.TimeUnit;
+import org.jetbrains.annotations.ApiStatus;
+import org.jetbrains.annotations.NotNull;
+
+/**
+ * Measures how long something took, on a {@link MonotonicClock}.
+ *
+ * <p>The counterpart to {@link Deadline}: it keeps the start tick and the unit conversion in one
+ * place, so call sites stop repeating {@code System.nanoTime() - startTime}.
+ */
+@ApiStatus.Internal
+public final class Stopwatch {
+
+  private final @NotNull MonotonicClock clock;
+  private final long startNanos;
+
+  private Stopwatch(final @NotNull MonotonicClock clock) {
+    this.clock = clock;
+    this.startNanos = clock.tickNanos();
+  }
+
+  public static @NotNull Stopwatch started(final @NotNull MonotonicClock clock) {
+    return new Stopwatch(clock);
+  }
+
+  public long elapsedNanos() {
+    return clock.tickNanos() - startNanos;
+  }
+
+  public long elapsed(final @NotNull TimeUnit unit) {
+    return unit.convert(elapsedNanos(), TimeUnit.NANOSECONDS);
+  }
+}