[libvirt] [PATCH] virobject: Improve documentation
I had to inspect the code to learn whether a final virObjectUnref()
calls ALL dispose callbacks in child-to-parent order (akin to C++
destructors), or whether I manually had to call a parent-class dispose
when writing a child class dispose method. The answer is the
former. (Thankfully, since VIR_FREE wipes out pointers for safety,
even if I had guessed wrong, I probably would not have tripped over a
double-free fault when the parent dispose ran for the second time).
While at it, the VIR_CLASS_NEW macro requires that the virObject
component at offset 0 be reached through the name 'parent', not
'object'.
Signed-off-by: Eric Blake <eblake(a)redhat.com>
---
src/util/virobject.c | 9 +++++----
1 file changed, 5 insertions(+), 4 deletions(-)
diff --git a/src/util/virobject.c b/src/util/virobject.c
index f08c18ce44..462b3d7d3f 100644
--- a/src/util/virobject.c
+++ b/src/util/virobject.c
@@ -147,10 +147,11 @@ virClassForObjectRWLockable(void)
*
* Register a new object class with @name. The @objectSize
* should give the total size of the object struct, which
- * is expected to have a 'virObject object;' field as its
- * first member. When the last reference on the object is
- * released, the @dispose callback will be invoked to free
- * memory of the object fields
+ * is expected to have a 'virObject parent;' field as (or
+ * contained in) its first member. When the last reference
+ * on the object is released, the @dispose callback will be
+ * invoked to free memory of the local object fields, as
+ * well as dispose callbacks of the parent classes
*
* Returns a new class instance
*/
--
2.20.1