From 35887bc2a68e31b0942fb402622c6a1b5a03235a Mon Sep 17 00:00:00 2001 From: Santiago Seifert Date: Tue, 19 Oct 2021 13:45:30 +0100 Subject: [PATCH] Document MediaPlayer.release to be mandatory Finalizers and cleaners are discouraged java practices. Concretely, counting on finalize to release MediaPlayer violates the requirement of single-threaded use in the class javadoc. Bug: 182712404 Bug: 201440544 Test: N/A. Javadoc only change. Change-Id: I920860a8ff49d0a6bd9cef321f69269194d5fd39 --- media/java/android/media/MediaPlayer.java | 68 +++++++++-------------- 1 file changed, 26 insertions(+), 42 deletions(-) diff --git a/media/java/android/media/MediaPlayer.java b/media/java/android/media/MediaPlayer.java index 83bc38b217175..10772754bd6cb 100644 --- a/media/java/android/media/MediaPlayer.java +++ b/media/java/android/media/MediaPlayer.java @@ -158,18 +158,10 @@ import java.util.concurrent.Executor; * the user supplied callback method OnErrorListener.onError() will be * invoked by the internal player engine and the object will be * transfered to the Error state. - *
  • It is also recommended that once - * a MediaPlayer object is no longer being used, call {@link #release()} immediately - * so that resources used by the internal player engine associated with the - * MediaPlayer object can be released immediately. Resource may include - * singleton resources such as hardware acceleration components and - * failure to call {@link #release()} may cause subsequent instances of - * MediaPlayer objects to fallback to software implementations or fail - * altogether. Once the MediaPlayer - * object is in the End state, it can no longer be used and - * there is no way to bring it back to any other state.
    • - *
  • Furthermore, - * the MediaPlayer objects created using new is in the + *
  • You must call {@link #release()} once you have finished using an instance to release + * acquired resources, such as memory and codecs. Once you have called {@link #release}, you + * must no longer interact with the released instance. + *
  • MediaPlayer objects created using new is in the * Idle state, while those created with one * of the overloaded convenient create methods are NOT * in the Idle state. In fact, the objects are in the Prepared @@ -407,7 +399,7 @@ import java.util.concurrent.Executor; * release

    * any

    * {}

    - * After {@link #release()}, the object is no longer available.

    + * After {@link #release()}, you must not interact with the object.

    * reset

    * {Idle, Initialized, Prepared, Started, Paused, Stopped, * PlaybackCompleted, Error}

    @@ -657,11 +649,13 @@ public class MediaPlayer extends PlayerBase private ProvisioningThread mDrmProvisioningThread; /** - * Default constructor. Consider using one of the create() methods for - * synchronously instantiating a MediaPlayer from a Uri or resource. - *

    When done with the MediaPlayer, you should call {@link #release()}, - * to free the resources. If not released, too many MediaPlayer instances may - * result in an exception.

    + * Default constructor. + * + *

    Consider using one of the create() methods for synchronously instantiating a MediaPlayer + * from a Uri or resource. + * + *

    You must call {@link #release()} when you are finished using the instantiated instance. + * Doing so frees any resources you have previously acquired. */ public MediaPlayer() { this(AudioSystem.AUDIO_SESSION_ALLOCATE); @@ -873,9 +867,10 @@ public class MediaPlayer extends PlayerBase /** * Convenience method to create a MediaPlayer for a given Uri. * On success, {@link #prepare()} will already have been called and must not be called again. - *

    When done with the MediaPlayer, you should call {@link #release()}, - * to free the resources. If not released, too many MediaPlayer instances will - * result in an exception.

    + * + *

    You must call {@link #release()} when you are finished using the created instance. Doing + * so frees any resources you have previously acquired. + * *

    Note that since {@link #prepare()} is called automatically in this method, * you cannot change the audio * session ID (see {@link #setAudioSessionId(int)}) or audio attributes @@ -892,9 +887,10 @@ public class MediaPlayer extends PlayerBase /** * Convenience method to create a MediaPlayer for a given Uri. * On success, {@link #prepare()} will already have been called and must not be called again. - *

    When done with the MediaPlayer, you should call {@link #release()}, - * to free the resources. If not released, too many MediaPlayer instances will - * result in an exception.

    + * + *

    You must call {@link #release()} when you are finished using the created instance. Doing + * so frees any resources you have previously acquired. + * *

    Note that since {@link #prepare()} is called automatically in this method, * you cannot change the audio * session ID (see {@link #setAudioSessionId(int)}) or audio attributes @@ -955,9 +951,10 @@ public class MediaPlayer extends PlayerBase /** * Convenience method to create a MediaPlayer for a given resource id. * On success, {@link #prepare()} will already have been called and must not be called again. - *

    When done with the MediaPlayer, you should call {@link #release()}, - * to free the resources. If not released, too many MediaPlayer instances will - * result in an exception.

    + * + *

    You must call {@link #release()} when you are finished using the created instance. Doing + * so frees any resources you have previously acquired. + * *

    Note that since {@link #prepare()} is called automatically in this method, * you cannot change the audio * session ID (see {@link #setAudioSessionId(int)}) or audio attributes @@ -2157,21 +2154,8 @@ public class MediaPlayer extends PlayerBase /** * Releases resources associated with this MediaPlayer object. - * It is considered good practice to call this method when you're - * done using the MediaPlayer. In particular, whenever an Activity - * of an application is paused (its onPause() method is called), - * or stopped (its onStop() method is called), this method should be - * invoked to release the MediaPlayer object, unless the application - * has a special need to keep the object around. In addition to - * unnecessary resources (such as memory and instances of codecs) - * being held, failure to call this method immediately if a - * MediaPlayer object is no longer needed may also lead to - * continuous battery consumption for mobile devices, and playback - * failure for other applications if no multiple instances of the - * same codec are supported on a device. Even if multiple instances - * of the same codec are supported, some performance degradation - * may be expected when unnecessary multiple instances are used - * at the same time. + * + *

    You must call this method once the instance is no longer required. */ public void release() { baseRelease();