libbinder: document attach/find/detach object
Bug: 114127243
Test: N/A
Change-Id: Ifc30542e0908b45e4cb512804787ae2b59dc2c8e
diff --git a/libs/binder/include/binder/IBinder.h b/libs/binder/include/binder/IBinder.h
index 318070a..3f0dad0 100644
--- a/libs/binder/include/binder/IBinder.h
+++ b/libs/binder/include/binder/IBinder.h
@@ -151,11 +151,31 @@
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();