Add ExoPlayer.setForegroundMode

Issue: #2826

-------------
Created by MOE: https://github.com/google/moe
MOE_MIGRATED_REVID=217189082

RELEASENOTES.md

@@ -2,6 +2,8 @@
 
 ### dev-v2 (not yet released) ###
 
+* Improve decoder re-use between playbacks. TODO: Write and link a blog post
+  here ([#2826](https://github.com/google/ExoPlayer/issues/2826)).
 * Improve initial bandwidth meter estimates using the current country and
   network type.
 * Do not retry failed loads whose error is `FileNotFoundException`.

library/core/src/main/java/com/google/android/exoplayer2/ExoPlayer.java

@@ -209,4 +209,34 @@ public interface ExoPlayer extends Player {
 
   /** Returns the currently active {@link SeekParameters} of the player. */
   SeekParameters getSeekParameters();
+
+  /**
+   * Sets whether the player is allowed to keep holding limited resources such as video decoders,
+   * even when in the idle state. By doing so, the player may be able to reduce latency when
+   * starting to play another piece of content for which the same resources are required.
+   *
+   * <p>This mode should be used with caution, since holding limited resources may prevent other
+   * players of media components from acquiring them. It should only be enabled when <em>both</em>
+   * of the following conditions are true:
+   *
+   * <ul>
+   *   <li>The application that owns the player is in the foreground.
+   *   <li>The player is used in a way that may benefit from foreground mode. For this to be true,
+   *       the same player instance must be used to play multiple pieces of content, and there must
+   *       be gaps between the playbacks (i.e. {@link #stop} is called to halt one playback, and
+   *       {@link #prepare} is called some time later to start a new one).
+   * </ul>
+   *
+   * <p>Note that foreground mode is <em>not</em> useful for switching between content without gaps
+   * between the playbacks. For this use case {@link #stop} does not need to be called, and simply
+   * calling {@link #prepare} for the new media will cause limited resources to be retained even if
+   * foreground mode is not enabled.
+   *
+   * <p>If foreground mode is enabled, it's the application's responsibility to disable it when the
+   * conditions described above no longer hold.
+   *
+   * @param foregroundMode Whether the player is allowed to keep limited resources even when in the
+   *     idle state.
+   */
+  void setForegroundMode(boolean foregroundMode);
 }

library/core/src/main/java/com/google/android/exoplayer2/ExoPlayerImpl.java

@@ -71,6 +71,7 @@ import java.util.concurrent.CopyOnWriteArraySet;
   private int pendingOperationAcks;
   private boolean hasPendingPrepare;
   private boolean hasPendingSeek;
+  private boolean foregroundMode;
   private PlaybackParameters playbackParameters;
   private SeekParameters seekParameters;
   private @Nullable ExoPlaybackException playbackError;
@@ -360,6 +361,14 @@ import java.util.concurrent.CopyOnWriteArraySet;
   }
 
   @Override
+  public void setForegroundMode(boolean foregroundMode) {
+    if (this.foregroundMode != foregroundMode) {
+      this.foregroundMode = foregroundMode;
+      internalPlayer.setForegroundMode(foregroundMode);
+    }
+  }
+
+  @Override
   public void stop(boolean reset) {
     if (reset) {
       playbackError = null;

library/core/src/main/java/com/google/android/exoplayer2/SimpleExoPlayer.java

@@ -959,6 +959,11 @@ public class SimpleExoPlayer extends BasePlayer
   }
 
   @Override
+  public void setForegroundMode(boolean foregroundMode) {
+    player.setForegroundMode(foregroundMode);
+  }
+
+  @Override
   public void stop(boolean reset) {
     verifyApplicationThread();
     player.stop(reset);

testutils_robolectric/src/main/java/com/google/android/exoplayer2/testutil/StubExoPlayer.java

@@ -267,4 +267,9 @@ public abstract class StubExoPlayer extends BasePlayer implements ExoPlayer {
   public long getContentBufferedPosition() {
     throw new UnsupportedOperationException();
   }
+
+  @Override
+  public void setForegroundMode(boolean foregroundMode) {
+    throw new UnsupportedOperationException();
+  }
 }