Re: [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&gt; --- 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