Clarify details in docs for binderDied()
Bug: 323587535
Test: none
Change-Id: I8d9f9b4ddc10145744107dd78c7e1e3516f5c18d
diff --git a/core/java/android/os/IBinder.java b/core/java/android/os/IBinder.java
index 91c2965..c9f207c 100644
--- a/core/java/android/os/IBinder.java
+++ b/core/java/android/os/IBinder.java
@@ -305,15 +305,28 @@
/**
* 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) {