Add max time diff setting for auto-advancing FakeClock

The auto advancing feature assumes there is a regular driver that
pushes the time forward in small-ish increments (as done in ExoPlayer).

This logic can break if:
 - There is process generating new messages out of control of the
   clock (e.g. a Loader in ExoPlayer)
 - The message queue has another timed message much further in
   the future that was never meant to drive the clock forward.

This issue can be avoided by imposing a maximum expected time diff
for the clock auto-advancing mechanism. Choosing 1 second by default
should work well for all (Exo)Player use cases even with dynamic
scheduling of updates. Also adding a Builder to make this configurable
if required.

PiperOrigin-RevId: 784194600

Author: tonihei

RELEASENOTES.md

@@ -102,6 +102,8 @@
     *   Stop enforcing a non-null mime type in `DefaultMediaItemConverter`.
     *   Enable remote to local transfers in `DefaultCastOptionsProvider`.
 *   Test Utilities:
+    *   Add maximum time diff for the auto-advancing behavior of `FakeClock`. It
+        defaults to 1 second, but is configurable via `FakeClock.Builder`.
 *   Remove deprecated symbols:
 
 ## 1.8

libraries/test_utils/src/main/java/androidx/media3/test/utils/FakeClock.java

@@ -31,6 +31,7 @@
 import com.google.common.collect.ComparisonChain;
 import com.google.common.collect.ImmutableSet;
 import com.google.common.collect.Ordering;
+import com.google.errorprone.annotations.CanIgnoreReturnValue;
 import java.util.ArrayList;
 import java.util.Collections;
 import java.util.HashSet;
@@ -55,6 +56,95 @@
 @UnstableApi
 public class FakeClock implements Clock {
 
+  /** A builder for {@link FakeClock} instances. */
+  public static final class Builder {
+    private long bootTimeMs;
+    private long initialTimeMs;
+    private boolean isAutoAdvancing;
+    private long maxAutoAdvancingTimeDiffMs;
+
+    /** Creates a new builder for {@link FakeClock} instances. */
+    public Builder() {
+      bootTimeMs = 0;
+      initialTimeMs = 0;
+      isAutoAdvancing = false;
+      maxAutoAdvancingTimeDiffMs = DEFAULT_MAX_AUTO_ADVANCING_TIME_DIFF_MS;
+    }
+
+    /**
+     * Sets the time the system was booted since the Unix Epoch, in milliseconds.
+     *
+     * <p>The default value is 0.
+     *
+     * @param bootTimeMs The time the system was booted since the Unix Epoch, in milliseconds.
+     * @return This builder.
+     */
+    @CanIgnoreReturnValue
+    public Builder setBootTimeMs(long bootTimeMs) {
+      this.bootTimeMs = bootTimeMs;
+      return this;
+    }
+
+    /**
+     * Sets the initial elapsed time since the boot time, in milliseconds.
+     *
+     * <p>The default value is 0.
+     *
+     * @param initialTimeMs The initial elapsed time since the boot time, in milliseconds.
+     * @return This builder.
+     */
+    @CanIgnoreReturnValue
+    public Builder setInitialTimeMs(long initialTimeMs) {
+      this.initialTimeMs = initialTimeMs;
+      return this;
+    }
+
+    /**
+     * Sets whether the clock should automatically advance the time to the time of the next message
+     * that is due to be sent.
+     *
+     * <p>The default value is false.
+     *
+     * @param isAutoAdvancing Whether the clock should automatically advance the time.
+     * @return This builder.
+     */
+    @CanIgnoreReturnValue
+    public Builder setIsAutoAdvancing(boolean isAutoAdvancing) {
+      this.isAutoAdvancing = isAutoAdvancing;
+      return this;
+    }
+
+    /**
+     * Sets the maximum time difference between two messages that the fake clock will automatically
+     * advance.
+     *
+     * <p>The default value is {@link #DEFAULT_MAX_AUTO_ADVANCING_TIME_DIFF_MS}.
+     *
+     * @param maxAutoAdvancingTimeDiffMs The maximum time difference in milliseconds.
+     * @return This builder.
+     */
+    @CanIgnoreReturnValue
+    public Builder setMaxAutoAdvancingTimeDiffMs(long maxAutoAdvancingTimeDiffMs) {
+      this.maxAutoAdvancingTimeDiffMs = maxAutoAdvancingTimeDiffMs;
+      return this;
+    }
+
+    /**
+     * Builds a {@link FakeClock} instance.
+     *
+     * @return The built {@link FakeClock} instance.
+     */
+    public FakeClock build() {
+      return new FakeClock(/* builder= */ this);
+    }
+  }
+
+  /**
+   * The default maximum time difference between two messages that the fake clock will automatically
+   * advance.
+   */
+  public static final long DEFAULT_MAX_AUTO_ADVANCING_TIME_DIFF_MS = 1000;
+
   private static final ImmutableSet<String> UI_INTERACTION_TEST_CLASSES =
       ImmutableSet.of(
           "org.robolectric.android.internal.LocalControlledLooper",
@@ -69,6 +159,7 @@ public class FakeClock implements Clock {
   private final boolean isRobolectric;
   private final boolean isAutoAdvancing;
   private final Handler mainHandler;
+  private final long maxAutoAdvancingTimeDiffMs;
 
   @GuardedBy("this")
   private final List<HandlerMessage> handlerMessages;
@@ -129,15 +220,24 @@ public FakeClock(long initialTimeMs, boolean isAutoAdvancing) {
    *     next message that is due to be sent.
    */
   public FakeClock(long bootTimeMs, long initialTimeMs, boolean isAutoAdvancing) {
-    this.bootTimeMs = bootTimeMs;
-    this.timeSinceBootMs = initialTimeMs;
-    this.isAutoAdvancing = isAutoAdvancing;
+    this(
+        new Builder()
+            .setBootTimeMs(bootTimeMs)
+            .setInitialTimeMs(initialTimeMs)
+            .setIsAutoAdvancing(isAutoAdvancing));
+  }
+
+  private FakeClock(Builder builder) {
+    this.bootTimeMs = builder.bootTimeMs;
+    this.timeSinceBootMs = builder.initialTimeMs;
+    this.isAutoAdvancing = builder.isAutoAdvancing;
+    this.maxAutoAdvancingTimeDiffMs = builder.maxAutoAdvancingTimeDiffMs;
     this.handlerMessages = new ArrayList<>();
     this.busyLoopers = new HashSet<>();
     this.mainHandler = new Handler(Looper.getMainLooper());
     this.isRobolectric = "robolectric".equals(Build.FINGERPRINT);
     if (isRobolectric) {
-      SystemClock.setCurrentTimeMillis(initialTimeMs);
+      SystemClock.setCurrentTimeMillis(builder.initialTimeMs);
     }
   }
 
@@ -271,8 +371,9 @@ private synchronized void maybeTriggerMessage() {
       return;
     }
     if (message.timeMs > timeSinceBootMs) {
-      if (isAutoAdvancing) {
-        advanceTimeInternal(message.timeMs - timeSinceBootMs);
+      long timeDiff = message.timeMs - timeSinceBootMs;
+      if (isAutoAdvancing && timeDiff <= maxAutoAdvancingTimeDiffMs) {
+        advanceTimeInternal(timeDiff);
       } else {
         return;
       }

libraries/test_utils/src/test/java/androidx/media3/test/utils/FakeClockTest.java

@@ -321,6 +321,38 @@ public void createHandler_withIsAutoAdvancing_advancesTimeToNextMessages() {
     assertThat(clockTimes).containsExactly(0L, 20L, 50L, 70L, 100L).inOrder();
   }
 
+  @Test
+  public void createHandler_withIsAutoAdvancing_triggersOnlyMessagesWithinDefinedMaxTimeDiff() {
+    HandlerThread handlerThread = new HandlerThread("FakeClockTest");
+    handlerThread.start();
+    FakeClock fakeClock =
+        new FakeClock.Builder()
+            .setInitialTimeMs(0)
+            .setIsAutoAdvancing(true)
+            .setMaxAutoAdvancingTimeDiffMs(400)
+            .build();
+    HandlerWrapper handler =
+        fakeClock.createHandler(handlerThread.getLooper(), /* callback= */ null);
+
+    // Post a series of immediate and delayed messages with one that is too far in the future.
+    ArrayList<Long> clockTimes = new ArrayList<>();
+    handler.post(
+        () -> {
+          handler.postDelayed(
+              () -> clockTimes.add(fakeClock.elapsedRealtime()), /* delayMs= */ 400);
+          handler.postDelayed(
+              () -> clockTimes.add(fakeClock.elapsedRealtime()), /* delayMs= */ 801);
+          handler.post(() -> clockTimes.add(fakeClock.elapsedRealtime()));
+          handler.postDelayed(
+              () -> clockTimes.add(fakeClock.elapsedRealtime()), /* delayMs= */ 200);
+        });
+    ShadowLooper.idleMainLooper();
+    shadowOf(handler.getLooper()).idle();
+    handlerThread.quitSafely();
+
+    assertThat(clockTimes).containsExactly(0L, 200L, 400L).inOrder();
+  }
+
   @Test
   public void createHandler_multiThreadCommunication_deliversMessagesDeterministicallyInOrder()
       throws Exception {