From 19878b0b8b3bc13338cb06341133f96f3e25f532 Mon Sep 17 00:00:00 2001
From: huangdarwin <huangdarwin@google.com>
Date: Thu, 7 Sep 2023 05:59:15 -0700
Subject: [PATCH] Effect: Clearly state what callers must do onError.

Instead of invoking "undefined behavior" may occur when a class is used
incorrectly, which is clear but not very helpful to callers, specify what Apps
or users of a class should do when issues occur.

Apply this to Compositor as well, where this otherwise might seem unclear.

PiperOrigin-RevId: 563406219
---
 .../java/androidx/media3/common/VideoFrameProcessor.java | 5 ++++-
 .../java/androidx/media3/effect/VideoCompositor.java     | 9 +++++++--
 .../media3/effect/VideoFrameProcessingTaskExecutor.java  | 7 +++++--
 3 files changed, 16 insertions(+), 5 deletions(-)

diff --git a/libraries/common/src/main/java/androidx/media3/common/VideoFrameProcessor.java b/libraries/common/src/main/java/androidx/media3/common/VideoFrameProcessor.java
index 12b94165db..6c8549a75b 100644
--- a/libraries/common/src/main/java/androidx/media3/common/VideoFrameProcessor.java
+++ b/libraries/common/src/main/java/androidx/media3/common/VideoFrameProcessor.java
@@ -149,7 +149,8 @@ public interface VideoFrameProcessor {
     /**
      * Called when an exception occurs during asynchronous video frame processing.
      *
-     * <p>Using {@code VideoFrameProcessor} after an error happens is undefined behavior.
+     * <p>If this is called, the calling {@link VideoFrameProcessor} must immediately be {@linkplain
+     * VideoFrameProcessor#release() released}.
      */
     void onError(VideoFrameProcessingException exception);
 
@@ -345,6 +346,8 @@ public interface VideoFrameProcessor {
    * <p>This method blocks until all resources are released or releasing times out.
    *
    * <p>Can be called on any thread.
+   *
+   * <p>This {@link VideoFrameProcessor} instance must not be used after this method is called.
    */
   void release();
 }
diff --git a/libraries/effect/src/main/java/androidx/media3/effect/VideoCompositor.java b/libraries/effect/src/main/java/androidx/media3/effect/VideoCompositor.java
index 63734893e7..14ad61a1ac 100644
--- a/libraries/effect/src/main/java/androidx/media3/effect/VideoCompositor.java
+++ b/libraries/effect/src/main/java/androidx/media3/effect/VideoCompositor.java
@@ -35,7 +35,8 @@ public interface VideoCompositor extends GlTextureProducer {
     /**
      * Called when an exception occurs during asynchronous frame compositing.
      *
-     * <p>Using {@link VideoCompositor} after an error happens is undefined behavior.
+     * <p>If this is called, the calling {@link VideoCompositor} must immediately be {@linkplain
+     * VideoCompositor#release() released}.
      */
     void onError(VideoFrameProcessingException exception);
 
@@ -87,6 +88,10 @@ public interface VideoCompositor extends GlTextureProducer {
       GlTextureInfo inputTexture,
       long presentationTimeUs);
 
-  /** Releases all resources. */
+  /**
+   * Releases all resources.
+   *
+   * <p>This {@link VideoCompositor} instance must not be used after this method is called.
+   */
   void release();
 }
diff --git a/libraries/effect/src/main/java/androidx/media3/effect/VideoFrameProcessingTaskExecutor.java b/libraries/effect/src/main/java/androidx/media3/effect/VideoFrameProcessingTaskExecutor.java
index 25428dc311..5e71a72312 100644
--- a/libraries/effect/src/main/java/androidx/media3/effect/VideoFrameProcessingTaskExecutor.java
+++ b/libraries/effect/src/main/java/androidx/media3/effect/VideoFrameProcessingTaskExecutor.java
@@ -57,8 +57,8 @@ import java.util.concurrent.RejectedExecutionException;
     /**
      * Called when an exception occurs while executing submitted tasks.
      *
-     * <p>Using the {@link VideoFrameProcessingTaskExecutor} after an error happens is undefined
-     * behavior.
+     * <p>If this is called, the calling {@link VideoFrameProcessingTaskExecutor} must immediately
+     * be {@linkplain VideoFrameProcessingTaskExecutor#release} released}.
      */
     void onError(VideoFrameProcessingException exception);
   }
@@ -160,6 +160,9 @@ import java.util.concurrent.RejectedExecutionException;
    * <p>If {@code shouldShutdownExecutorService} is {@code true}, shuts down the {@linkplain
    * ExecutorService background thread}.
    *
+   * <p>This {@link VideoFrameProcessingTaskExecutor} instance must not be used after this method is
+   * called.
+   *
    * @param releaseTask A {@link Task} to execute before shutting down the background thread.
    * @throws InterruptedException If interrupted while releasing resources.
    */