Add support for preparing DRM sessions before they're needed

This adds an optional DrmSessionManager#preacquireSession() method
and implements it on DefaultDrmSessionManager.

The manager doesn't promise to keep the preacquired sessions alive, and
will proactively release them if a ResourceBusyException suggests the
device is running out of available sessions in the underlying framework.

In a future change, SampleQueue will preacquire sessions on the loading
thread and keep track of preacquired 'references', releasing them
when seeking or clearing the queue.

Issue: #4133
PiperOrigin-RevId: 358381616

library/core/src/main/java/com/google/android/exoplayer2/drm/DrmSessionManager.java

@@ -22,6 +22,23 @@ import com.google.android.exoplayer2.Format;
 /** Manages a DRM session. */
 /** Manages a DRM session. */
 public interface DrmSessionManager {
 public interface DrmSessionManager {
 
 
+  /**
+   * Represents a single reference count of a {@link DrmSession}, while deliberately not giving
+   * access to the underlying session.
+   */
+  interface DrmSessionReference {
+    /** A reference that is never populated with an underlying {@link DrmSession}. */
+    DrmSessionReference EMPTY = () -> {};
+
+    /**
+     * Releases the underlying session at most once.
+     *
+     * <p>Can be called from any thread. Calling this method more than once will only release the
+     * underlying session once.
+     */
+    void release();
+  }
+
   /** An instance that supports no DRM schemes. */
   /** An instance that supports no DRM schemes. */
   DrmSessionManager DRM_UNSUPPORTED =
   DrmSessionManager DRM_UNSUPPORTED =
       new DrmSessionManager() {
       new DrmSessionManager() {
@@ -82,6 +99,51 @@ public interface DrmSessionManager {
   }
   }
 
 
   /**
   /**
+   * Pre-acquires a DRM session for the specified {@link Format}.
+   *
+   * <p>This notifies the manager that a subsequent call to {@link #acquireSession(Looper,
+   * DrmSessionEventListener.EventDispatcher, Format)} with the same {@link Format} is likely,
+   * allowing a manager that supports pre-acquisition to get the required {@link DrmSession} ready
+   * in the background.
+   *
+   * <p>The caller must call {@link DrmSessionReference#release()} on the returned instance when
+   * they no longer require the pre-acquisition (i.e. they know they won't be making a matching call
+   * to {@link #acquireSession(Looper, DrmSessionEventListener.EventDispatcher, Format)} in the near
+   * future).
+   *
+   * <p>This manager may silently release the underlying session in order to allow another operation
+   * to complete. This will result in a subsequent call to {@link #acquireSession(Looper,
+   * DrmSessionEventListener.EventDispatcher, Format)} re-initializing a new session, including
+   * repeating key loads and other async initialization steps.
+   *
+   * <p>The caller must separately call {@link #acquireSession(Looper,
+   * DrmSessionEventListener.EventDispatcher, Format)} in order to obtain a session suitable for
+   * playback. The pre-acquired {@link DrmSessionReference} and full {@link DrmSession} instances
+   * are distinct. The caller must release both, and can release the {@link DrmSessionReference}
+   * before the {@link DrmSession} without affecting playback.
+   *
+   * <p>This can be called from any thread.
+   *
+   * <p>Implementations that do not support pre-acquisition always return an empty {@link
+   * DrmSessionReference} instance.
+   *
+   * @param playbackLooper The looper associated with the media playback thread.
+   * @param eventDispatcher The {@link DrmSessionEventListener.EventDispatcher} used to distribute
+   *     events, and passed on to {@link
+   *     DrmSession#acquire(DrmSessionEventListener.EventDispatcher)}.
+   * @param format The {@link Format} for which to pre-acquire a {@link DrmSession}.
+   * @return A releaser for the pre-acquired session. Guaranteed to be non-null even if the matching
+   *     {@link #acquireSession(Looper, DrmSessionEventListener.EventDispatcher, Format)} would
+   *     return null.
+   */
+  default DrmSessionReference preacquireSession(
+      Looper playbackLooper,
+      @Nullable DrmSessionEventListener.EventDispatcher eventDispatcher,
+      Format format) {
+    return DrmSessionReference.EMPTY;
+  }
+
+  /**
    * Returns a {@link DrmSession} for the specified {@link Format}, with an incremented reference
    * Returns a {@link DrmSession} for the specified {@link Format}, with an incremented reference
    * count. May return null if the {@link Format#drmInitData} is null and the DRM session manager is
    * count. May return null if the {@link Format#drmInitData} is null and the DRM session manager is
    * not configured to attach a {@link DrmSession} to clear content. When the caller no longer needs
    * not configured to attach a {@link DrmSession} to clear content. When the caller no longer needs

library/core/src/test/java/com/google/android/exoplayer2/drm/DefaultDrmSessionManagerTest.java

@@ -20,14 +20,18 @@ import static com.google.common.truth.Truth.assertThat;
 import static java.util.concurrent.TimeUnit.SECONDS;
 import static java.util.concurrent.TimeUnit.SECONDS;
 
 
 import android.os.Looper;
 import android.os.Looper;
+import androidx.annotation.Nullable;
 import androidx.test.ext.junit.runners.AndroidJUnit4;
 import androidx.test.ext.junit.runners.AndroidJUnit4;
 import com.google.android.exoplayer2.C;
 import com.google.android.exoplayer2.C;
 import com.google.android.exoplayer2.Format;
 import com.google.android.exoplayer2.Format;
+import com.google.android.exoplayer2.source.MediaSource;
 import com.google.android.exoplayer2.testutil.FakeExoMediaDrm;
 import com.google.android.exoplayer2.testutil.FakeExoMediaDrm;
 import com.google.android.exoplayer2.testutil.TestUtil;
 import com.google.android.exoplayer2.testutil.TestUtil;
 import com.google.android.exoplayer2.util.MimeTypes;
 import com.google.android.exoplayer2.util.MimeTypes;
+import com.google.android.exoplayer2.util.Util;
 import com.google.common.collect.ImmutableList;
 import com.google.common.collect.ImmutableList;
 import java.util.UUID;
 import java.util.UUID;
+import java.util.concurrent.atomic.AtomicInteger;
 import org.junit.Test;
 import org.junit.Test;
 import org.junit.runner.RunWith;
 import org.junit.runner.RunWith;
 import org.robolectric.shadows.ShadowLooper;
 import org.robolectric.shadows.ShadowLooper;
@@ -38,6 +42,7 @@ import org.robolectric.shadows.ShadowLooper;
 // - Multiple acquisitions & releases for same keys -> multiple requests.
 // - Multiple acquisitions & releases for same keys -> multiple requests.
 // - Provisioning.
 // - Provisioning.
 // - Key denial.
 // - Key denial.
+// - Handling of ResourceBusyException (indicating session scarcity).
 @RunWith(AndroidJUnit4.class)
 @RunWith(AndroidJUnit4.class)
 public class DefaultDrmSessionManagerTest {
 public class DefaultDrmSessionManagerTest {
 
 
@@ -252,6 +257,156 @@ public class DefaultDrmSessionManagerTest {
     assertThat(secondDrmSession.getState()).isEqualTo(DrmSession.STATE_OPENED_WITH_KEYS);
     assertThat(secondDrmSession.getState()).isEqualTo(DrmSession.STATE_OPENED_WITH_KEYS);
   }
   }
 
 
+  @Test(timeout = 10_000)
+  public void preacquireSession_loadsKeysBeforeFullAcquisition() throws Exception {
+    AtomicInteger keyLoadCount = new AtomicInteger(0);
+    DrmSessionEventListener.EventDispatcher eventDispatcher =
+        new DrmSessionEventListener.EventDispatcher();
+    eventDispatcher.addEventListener(
+        Util.createHandlerForCurrentLooper(),
+        new DrmSessionEventListener() {
+          @Override
+          public void onDrmKeysLoaded(
+              int windowIndex, @Nullable MediaSource.MediaPeriodId mediaPeriodId) {
+            keyLoadCount.incrementAndGet();
+          }
+        });
+    FakeExoMediaDrm.LicenseServer licenseServer =
+        FakeExoMediaDrm.LicenseServer.allowingSchemeDatas(DRM_SCHEME_DATAS);
+    DrmSessionManager drmSessionManager =
+        new DefaultDrmSessionManager.Builder()
+            .setUuidAndExoMediaDrmProvider(DRM_SCHEME_UUID, uuid -> new FakeExoMediaDrm())
+            // Disable keepalive
+            .setSessionKeepaliveMs(C.TIME_UNSET)
+            .build(/* mediaDrmCallback= */ licenseServer);
+
+    drmSessionManager.prepare();
+
+    DrmSessionManager.DrmSessionReference sessionReference =
+        drmSessionManager.preacquireSession(
+            /* playbackLooper= */ checkNotNull(Looper.myLooper()),
+            eventDispatcher,
+            FORMAT_WITH_DRM_INIT_DATA);
+
+    // Wait for the key load event to propagate, indicating the pre-acquired session is in
+    // STATE_OPENED_WITH_KEYS.
+    while (keyLoadCount.get() == 0) {
+      // Allow the key response to be handled.
+      ShadowLooper.idleMainLooper();
+    }
+
+    DrmSession drmSession =
+        checkNotNull(
+            drmSessionManager.acquireSession(
+                /* playbackLooper= */ checkNotNull(Looper.myLooper()),
+                /* eventDispatcher= */ null,
+                FORMAT_WITH_DRM_INIT_DATA));
+
+    // Without idling the main/playback looper, we assert the session is already in OPENED_WITH_KEYS
+    assertThat(drmSession.getState()).isEqualTo(DrmSession.STATE_OPENED_WITH_KEYS);
+    assertThat(keyLoadCount.get()).isEqualTo(1);
+
+    // After releasing our concrete session reference, the session is held open by the pre-acquired
+    // reference.
+    drmSession.release(/* eventDispatcher= */ null);
+    assertThat(drmSession.getState()).isEqualTo(DrmSession.STATE_OPENED_WITH_KEYS);
+
+    // Releasing the pre-acquired reference allows the session to be fully released.
+    sessionReference.release();
+    assertThat(drmSession.getState()).isEqualTo(DrmSession.STATE_RELEASED);
+  }
+
+  @Test(timeout = 10_000)
+  public void
+      preacquireSession_releaseBeforeUnderlyingAcquisitionCompletesReleasesSessionOnceAcquired()
+          throws Exception {
+    FakeExoMediaDrm.LicenseServer licenseServer =
+        FakeExoMediaDrm.LicenseServer.allowingSchemeDatas(DRM_SCHEME_DATAS);
+    DrmSessionManager drmSessionManager =
+        new DefaultDrmSessionManager.Builder()
+            .setUuidAndExoMediaDrmProvider(DRM_SCHEME_UUID, uuid -> new FakeExoMediaDrm())
+            // Disable keepalive
+            .setSessionKeepaliveMs(C.TIME_UNSET)
+            .build(/* mediaDrmCallback= */ licenseServer);
+
+    drmSessionManager.prepare();
+
+    DrmSessionManager.DrmSessionReference sessionReference =
+        drmSessionManager.preacquireSession(
+            /* playbackLooper= */ checkNotNull(Looper.myLooper()),
+            /* eventDispatcher= */ null,
+            FORMAT_WITH_DRM_INIT_DATA);
+
+    // Release the pre-acquired reference before the underlying session has had a chance to be
+    // constructed.
+    sessionReference.release();
+
+    // Acquiring the same session triggers a second key load (because the pre-acquired session was
+    // fully released).
+    DrmSession drmSession =
+        checkNotNull(
+            drmSessionManager.acquireSession(
+                /* playbackLooper= */ checkNotNull(Looper.myLooper()),
+                /* eventDispatcher= */ null,
+                FORMAT_WITH_DRM_INIT_DATA));
+    assertThat(drmSession.getState()).isEqualTo(DrmSession.STATE_OPENED);
+
+    waitForOpenedWithKeys(drmSession);
+
+    drmSession.release(/* eventDispatcher= */ null);
+    assertThat(drmSession.getState()).isEqualTo(DrmSession.STATE_RELEASED);
+  }
+
+  @Test(timeout = 10_000)
+  public void preacquireSession_releaseManagerBeforeAcquisition_acquisitionDoesntHappen()
+      throws Exception {
+    FakeExoMediaDrm.LicenseServer licenseServer =
+        FakeExoMediaDrm.LicenseServer.allowingSchemeDatas(DRM_SCHEME_DATAS);
+    DrmSessionManager drmSessionManager =
+        new DefaultDrmSessionManager.Builder()
+            .setUuidAndExoMediaDrmProvider(DRM_SCHEME_UUID, uuid -> new FakeExoMediaDrm())
+            // Disable keepalive
+            .setSessionKeepaliveMs(C.TIME_UNSET)
+            .build(/* mediaDrmCallback= */ licenseServer);
+
+    drmSessionManager.prepare();
+
+    DrmSessionManager.DrmSessionReference sessionReference =
+        drmSessionManager.preacquireSession(
+            /* playbackLooper= */ checkNotNull(Looper.myLooper()),
+            /* eventDispatcher= */ null,
+            FORMAT_WITH_DRM_INIT_DATA);
+
+    // Release the manager before the underlying session has had a chance to be constructed. This
+    // will release all pre-acquired sessions.
+    drmSessionManager.release();
+
+    // Allow the acquisition event to be handled on the main/playback thread.
+    ShadowLooper.idleMainLooper();
+
+    // Re-prepare the manager so we can fully acquire the same session, and check the previous
+    // pre-acquisition didn't do anything.
+    drmSessionManager.prepare();
+    DrmSession drmSession =
+        checkNotNull(
+            drmSessionManager.acquireSession(
+                /* playbackLooper= */ checkNotNull(Looper.myLooper()),
+                /* eventDispatcher= */ null,
+                FORMAT_WITH_DRM_INIT_DATA));
+    assertThat(drmSession.getState()).isEqualTo(DrmSession.STATE_OPENED);
+    waitForOpenedWithKeys(drmSession);
+
+    drmSession.release(/* eventDispatcher= */ null);
+    // If the (still unreleased) pre-acquired session above was linked to the same underlying
+    // session then the state would still be OPENED_WITH_KEYS.
+    assertThat(drmSession.getState()).isEqualTo(DrmSession.STATE_RELEASED);
+
+    // Release the pre-acquired session from above (this is a no-op, but we do it anyway for
+    // correctness).
+    sessionReference.release();
+    drmSessionManager.release();
+  }
+
   private static void waitForOpenedWithKeys(DrmSession drmSession) {
   private static void waitForOpenedWithKeys(DrmSession drmSession) {
     // Check the error first, so we get a meaningful failure if there's been an error.
     // Check the error first, so we get a meaningful failure if there's been an error.
     assertThat(drmSession.getError()).isNull();
     assertThat(drmSession.getError()).isNull();