perf: Replace Timer threads with shared timer executor (JAVA-653)

RateLimiter and LifecycleWatcher each spun up a dedicated
java.util.Timer thread that stayed alive forever once created.
Schedule their tasks on the shared timer executor instead, whose
single worker thread is reused across all timeouts and
self-terminates when idle. This reduces the SDK's steady-state
thread count and memory footprint.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: runningcode

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

@@ -8,9 +8,7 @@
 import io.sentry.transport.CurrentDateProvider;
 import io.sentry.transport.ICurrentDateProvider;
 import io.sentry.util.AutoClosableReentrantLock;
-import io.sentry.util.LazyEvaluator;
-import java.util.Timer;
-import java.util.TimerTask;
+import java.util.concurrent.Future;
 import java.util.concurrent.atomic.AtomicLong;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
@@ -22,9 +20,8 @@ final class LifecycleWatcher implements AppState.AppStateListener {
 
   private final long sessionIntervalMillis;
 
-  private @Nullable TimerTask timerTask;
-  private final @NotNull LazyEvaluator<Timer> timer = new LazyEvaluator<>(() -> new Timer(true));
-  private final @NotNull AutoClosableReentrantLock timerLock = new AutoClosableReentrantLock();
+  private @Nullable Future<?> endSessionFuture;
+  private final @NotNull AutoClosableReentrantLock endSessionLock = new AutoClosableReentrantLock();
   private final @NotNull IScopes scopes;
   private final boolean enableSessionTracking;
   private final boolean enableAppLifecycleBreadcrumbs;
@@ -104,29 +101,40 @@ public void onBackground() {
   }
 
   private void scheduleEndSession() {
-    try (final @NotNull ISentryLifecycleToken ignored = timerLock.acquire()) {
+    try (final @NotNull ISentryLifecycleToken ignored = endSessionLock.acquire()) {
       cancelTask();
-      timerTask =
-          new TimerTask() {
-            @Override
-            public void run() {
-              if (enableSessionTracking) {
-                scopes.endSession();
-              }
-              scopes.getOptions().getReplayController().stop();
-              scopes.getOptions().getContinuousProfiler().close(false);
+      final @NotNull Runnable endSession =
+          () -> {
+            if (enableSessionTracking) {
+              scopes.endSession();
             }
+            scopes.getOptions().getReplayController().stop();
+            scopes.getOptions().getContinuousProfiler().close(false);
           };
 
-      timer.getValue().schedule(timerTask, sessionIntervalMillis);
+      try {
+        endSessionFuture =
+            scopes
+                .getOptions()
+                .getTimerExecutorService()
+                .schedule(endSession, sessionIntervalMillis);
+      } catch (Throwable e) {
+        scopes
+            .getOptions()
+            .getLogger()
+            .log(SentryLevel.WARNING, "Failed to schedule end of session. Ending it now.", e);
+        // if we cannot re-check after the session interval, end the session right away instead of
+        // leaving it open forever
+        endSession.run();
+      }
     }
   }
 
   private void cancelTask() {
-    try (final @NotNull ISentryLifecycleToken ignored = timerLock.acquire()) {
-      if (timerTask != null) {
-        timerTask.cancel();
-        timerTask = null;
+    try (final @NotNull ISentryLifecycleToken ignored = endSessionLock.acquire()) {
+      if (endSessionFuture != null) {
+        endSessionFuture.cancel(false);
+        endSessionFuture = null;
       }
     }
   }
@@ -144,13 +152,7 @@ private void addAppBreadcrumb(final @NotNull String state) {
 
   @TestOnly
   @Nullable
-  TimerTask getTimerTask() {
-    return timerTask;
-  }
-
-  @TestOnly
-  @NotNull
-  Timer getTimer() {
-    return timer.getValue();
+  Future<?> getEndSessionFuture() {
+    return endSessionFuture;
   }
 }

sentry-android-core/src/test/java/io/sentry/android/core/LifecycleWatcherTest.kt

@@ -7,6 +7,7 @@ import io.sentry.IScope
 import io.sentry.IScopes
 import io.sentry.ReplayController
 import io.sentry.ScopeCallback
+import io.sentry.SentryExecutorService
 import io.sentry.SentryLevel
 import io.sentry.SentryOptions
 import io.sentry.Session
@@ -32,7 +33,8 @@ class LifecycleWatcherTest {
   private class Fixture {
     val scopes = mock<IScopes>()
     val dateProvider = mock<ICurrentDateProvider>()
-    val options = SentryOptions()
+    // a real executor so scheduled end-session tasks actually run
+    val options = SentryOptions().apply { setTimerExecutorService(SentryExecutorService(this)) }
     val replayController = mock<ReplayController>()
     val continuousProfiler = mock<IContinuousProfiler>()
 
@@ -115,10 +117,10 @@ class LifecycleWatcherTest {
     watcher.onForeground()
 
     watcher.onBackground()
-    assertNotNull(watcher.timerTask)
+    assertNotNull(watcher.endSessionFuture)
 
     watcher.onForeground()
-    assertNull(watcher.timerTask)
+    assertNull(watcher.endSessionFuture)
 
     verify(fixture.scopes, never()).endSession()
     verify(fixture.replayController, never()).stop()
@@ -186,13 +188,6 @@ class LifecycleWatcherTest {
     verify(fixture.scopes, never()).addBreadcrumb(any<Breadcrumb>())
   }
 
-  @Test
-  fun `timer is created if session tracking is enabled`() {
-    val watcher =
-      fixture.getSUT(enableAutoSessionTracking = true, enableAppLifecycleBreadcrumbs = false)
-    assertNotNull(watcher.timer)
-  }
-
   @Test
   fun `if the scopes has already a fresh session running, don't start new one`() {
     val watcher =

sentry/src/main/java/io/sentry/transport/RateLimiter.java

@@ -23,12 +23,12 @@
 import java.util.Arrays;
 import java.util.Collections;
 import java.util.Date;
+import java.util.Iterator;
 import java.util.List;
 import java.util.Map;
-import java.util.Timer;
-import java.util.TimerTask;
 import java.util.concurrent.ConcurrentHashMap;
 import java.util.concurrent.CopyOnWriteArrayList;
+import java.util.concurrent.Future;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
@@ -42,8 +42,9 @@ public final class RateLimiter implements Closeable {
   private final @NotNull Map<DataCategory, @NotNull Date> sentryRetryAfterLimit =
       new ConcurrentHashMap<>();
   private final @NotNull List<IRateLimitObserver> rateLimitObservers = new CopyOnWriteArrayList<>();
-  private @Nullable Timer timer = null;
-  private final @NotNull AutoClosableReentrantLock timerLock = new AutoClosableReentrantLock();
+  private final @NotNull List<Future<?>> notifyObserversFutures = new ArrayList<>();
+  private final @NotNull AutoClosableReentrantLock notifyFuturesLock =
+      new AutoClosableReentrantLock();
 
   public RateLimiter(
       final @NotNull ICurrentDateProvider currentDateProvider,
@@ -278,11 +279,11 @@ public void updateRetryAfterLimits(
                   continue;
                 }
 
-                applyRetryAfterOnlyIfLonger(dataCategory, date);
+                applyRetryAfterOnlyIfLonger(dataCategory, date, retryAfterMillis);
               }
             } else {
               // if categories are empty, we should apply to "all" categories.
-              applyRetryAfterOnlyIfLonger(DataCategory.All, date);
+              applyRetryAfterOnlyIfLonger(DataCategory.All, date, retryAfterMillis);
             }
           }
         }
@@ -291,7 +292,7 @@ public void updateRetryAfterLimits(
       final long retryAfterMillis = parseRetryAfterOrDefault(retryAfterHeader);
       // we dont care if Date is UTC as we just add the relative seconds
       final Date date = new Date(currentDateProvider.getCurrentTimeMillis() + retryAfterMillis);
-      applyRetryAfterOnlyIfLonger(DataCategory.All, date);
+      applyRetryAfterOnlyIfLonger(DataCategory.All, date, retryAfterMillis);
     }
   }
 
@@ -300,10 +301,11 @@ public void updateRetryAfterLimits(
    *
    * @param dataCategory the DataCategory
    * @param date the Date to be applied
+   * @param delayMillis the millis until the rate limit is lifted
    */
   @SuppressWarnings({"JdkObsolete", "JavaUtilDate"})
   private void applyRetryAfterOnlyIfLonger(
-      final @NotNull DataCategory dataCategory, final @NotNull Date date) {
+      final @NotNull DataCategory dataCategory, final @NotNull Date date, final long delayMillis) {
     final Date oldDate = sentryRetryAfterLimit.get(dataCategory);
 
     // only overwrite its previous date if the limit is even longer
@@ -312,19 +314,25 @@ private void applyRetryAfterOnlyIfLonger(
 
       notifyRateLimitObservers();
 
-      try (final @NotNull ISentryLifecycleToken ignored = timerLock.acquire()) {
-        if (timer == null) {
-          timer = new Timer(true);
+      // notify observers again once the rate limit is lifted, using the shared timer executor
+      // instead of a dedicated Timer thread
+      try (final @NotNull ISentryLifecycleToken ignored = notifyFuturesLock.acquire()) {
+        final @NotNull Iterator<Future<?>> iterator = notifyObserversFutures.iterator();
+        while (iterator.hasNext()) {
+          if (iterator.next().isDone()) {
+            iterator.remove();
+          }
+        }
+        try {
+          notifyObserversFutures.add(
+              options
+                  .getTimerExecutorService()
+                  .schedule(() -> notifyRateLimitObservers(), delayMillis));
+        } catch (Throwable e) {
+          options
+              .getLogger()
+              .log(SentryLevel.WARNING, "Failed to schedule rate limit lifted notification.", e);
         }
-
-        timer.schedule(
-            new TimerTask() {
-              @Override
-              public void run() {
-                notifyRateLimitObservers();
-              }
-            },
-            date);
       }
     }
   }
@@ -364,11 +372,11 @@ public void removeRateLimitObserver(@NotNull final IRateLimitObserver observer)
 
   @Override
   public void close() throws IOException {
-    try (final @NotNull ISentryLifecycleToken ignored = timerLock.acquire()) {
-      if (timer != null) {
-        timer.cancel();
-        timer = null;
+    try (final @NotNull ISentryLifecycleToken ignored = notifyFuturesLock.acquire()) {
+      for (Future<?> future : notifyObserversFutures) {
+        future.cancel(false);
       }
+      notifyObserversFutures.clear();
     }
     rateLimitObservers.clear();
   }

sentry/src/test/java/io/sentry/transport/RateLimiterTest.kt

@@ -18,6 +18,7 @@ import io.sentry.SentryEnvelope
 import io.sentry.SentryEnvelopeHeader
 import io.sentry.SentryEnvelopeItem
 import io.sentry.SentryEvent
+import io.sentry.SentryExecutorService
 import io.sentry.SentryLogEvent
 import io.sentry.SentryLogEvents
 import io.sentry.SentryLogLevel
@@ -37,11 +38,10 @@ import io.sentry.protocol.SentryId
 import io.sentry.protocol.SentryTransaction
 import io.sentry.protocol.User
 import io.sentry.test.getProperty
-import io.sentry.test.injectForField
 import io.sentry.util.HintUtils
 import java.io.File
-import java.util.Timer
 import java.util.UUID
+import java.util.concurrent.Future
 import java.util.concurrent.atomic.AtomicBoolean
 import kotlin.test.Test
 import kotlin.test.assertEquals
@@ -66,6 +66,8 @@ class RateLimiterTest {
 
     fun getSUT(): RateLimiter {
       val options = SentryOptions().apply { setLogger(NoOpLogger.getInstance()) }
+      // a real executor so scheduled rate-limit-lifted notifications actually run
+      options.setTimerExecutorService(SentryExecutorService(options))
 
       SentryOptionsManipulator.setClientReportRecorder(options, clientReportRecorder)
 
@@ -654,7 +656,7 @@ class RateLimiterTest {
   }
 
   @Test
-  fun `apply rate limits schedules a timer to notify observers of lifted limits`() {
+  fun `apply rate limits schedules a task to notify observers of lifted limits`() {
     val rateLimiter = fixture.getSUT()
     whenever(fixture.currentDateProvider.currentTimeMillis).thenReturn(0, 1, 2001)
 
@@ -667,18 +669,19 @@ class RateLimiterTest {
   }
 
   @Test
-  fun `close cancels the timer`() {
+  fun `close cancels pending notify tasks`() {
     val rateLimiter = fixture.getSUT()
-    val timer = mock<Timer>()
-    rateLimiter.injectForField("timer", timer)
+    rateLimiter.updateRetryAfterLimits("60:replay:key", null, 1)
+
+    val futures = rateLimiter.getProperty<List<Future<*>>>("notifyObserversFutures")
+    assertEquals(1, futures.size)
+    val future = futures.first()
 
     // When the rate limiter is closed
     rateLimiter.close()
 
-    // Then the timer is cancelled
-    verify(timer).cancel()
-
-    // And is removed by the rateLimiter
-    assertNull(rateLimiter.getProperty("timer"))
+    // Then the pending notify task is cancelled and dropped
+    assertTrue(future.isCancelled)
+    assertTrue(rateLimiter.getProperty<List<Future<*>>>("notifyObserversFutures").isEmpty())
   }
 }