Clarify details in docs for binderDied()

Bug: 323587535
Test: none
Change-Id: I8d9f9b4ddc10145744107dd78c7e1e3516f5c18d

1 files changed, 15 insertions, 2 deletions

diff --git a/core/java/android/os/IBinder.java b/core/java/android/os/IBinder.java
index 91c2965c2505..c9f207cf26e8 100644
--- a/core/java/android/os/IBinder.java
+++ b/core/java/android/os/IBinder.java
@@ -305,15 +305,28 @@ public interface IBinder {
     /**
      * Interface for receiving a callback when the process hosting an IBinder
      * has gone away.
-     * 
+     *
      * @see #linkToDeath
      */
     public interface DeathRecipient {
         public void binderDied();
 
         /**
-         * Interface for receiving a callback when the process hosting an IBinder
+         * The function called when the process hosting an IBinder
          * has gone away.
+         *
+         * This callback will be called from any binder thread like any other binder
+         * transaction. If the process receiving this notification is multithreaded
+         * then synchronization may be required because other threads may be executing
+         * at the same time.
+         *
+         * No locks are held in libbinder when {@link binderDied} is called.
+         *
+         * There is no need to call {@link unlinkToDeath} in the binderDied callback.
+         * The binder is already dead so {@link unlinkToDeath} is a no-op.
+         * It will be unlinked when the last local reference of that binder proxy is
+         * dropped.
+         *
          * @param who The IBinder that has become invalid
          */
         default void binderDied(@NonNull IBinder who) {