Merge "libbinder: document attach/find/detach object"

1 files changed, 20 insertions, 0 deletions

diff --git a/libs/binder/include/binder/IBinder.h b/libs/binder/include/binder/IBinder.h
index 318070a2ac..3f0dad0f25 100644
--- a/libs/binder/include/binder/IBinder.h
+++ b/libs/binder/include/binder/IBinder.h
@@ -151,11 +151,31 @@ public:
 
     typedef void (*object_cleanup_func)(const void* id, void* obj, void* cleanupCookie);
 
+    /**
+     * This object is attached for the lifetime of this binder object. When
+     * this binder object is destructed, the cleanup function of all attached
+     * objects are invoked with their respective objectID, object, and
+     * cleanupCookie. Access to these APIs can be made from multiple threads,
+     * but calls from different threads are allowed to be interleaved.
+     */
     virtual void            attachObject(   const void* objectID,
                                             void* object,
                                             void* cleanupCookie,
                                             object_cleanup_func func) = 0;
+    /**
+     * Returns object attached with attachObject.
+     */
     virtual void*           findObject(const void* objectID) const = 0;
+    /**
+     * WARNING: this API does not call the cleanup function for legacy reasons.
+     * It also does not return void* for legacy reasons. If you need to detach
+     * an object and destroy it, there are two options:
+     * - if you can, don't call detachObject and instead wait for the destructor
+     *   to clean it up.
+     * - manually retrieve and destruct the object (if multiple of your threads
+     *   are accessing these APIs, you must guarantee that attachObject isn't
+     *   called after findObject and before detachObject is called).
+     */
     virtual void            detachObject(const void* objectID) = 0;
 
     virtual BBinder*        localBinder();