From: Eric Blake <eblake@redhat.com>
Date: Fri, 15 Mar 2019 04:14:41 +0000 (-0500)
Subject: virobject: Improve documentation
X-Git-Tag: v5.2.0-rc1~179
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=632ac8f8e7202ad848d0fbe3c2ca7e228dee1cef;p=thirdparty%2Flibvirt.git

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).  I
also had to read the code to learn if a dispose method was even
mandatory (it is not, although getting NULL through VIR_CLASS_NEW
requires a macro).  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@redhat.com>
Reviewed-by: Erik Skultety <eskultet@redhat.com>
---

diff --git a/src/util/virobject.c b/src/util/virobject.c
index f08c18ce44..3b28331ba7 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 the dispose callbacks of the parent classes.
  *
  * Returns a new class instance
  */
@@ -326,8 +327,9 @@ virObjectRWLockableDispose(void *anyobj)
  * @anyobj: any instance of virObjectPtr
  *
  * Decrement the reference count on @anyobj and if
- * it hits zero, runs the "dispose" callback associated
- * with the object class and frees @anyobj.
+ * it hits zero, runs the "dispose" callbacks associated
+ * with the object class and its parents before freeing
+ * @anyobj.
  *
  * Returns true if the remaining reference count is
  * non-zero, false if the object was disposed of
diff --git a/src/util/virobject.h b/src/util/virobject.h
index 56bc9f2324..d4ec943a43 100644
--- a/src/util/virobject.h
+++ b/src/util/virobject.h
@@ -75,6 +75,11 @@ virClassPtr virClassForObjectRWLockable(void);
 #  define VIR_PARENT_REQUIRED ATTRIBUTE_NONNULL(1)
 # endif
 
+/* Assign the class description nameClass to represent struct @name
+ * (which must have an object-based 'parent' member at offset 0), and
+ * with parent class @prnt. nameDispose must exist as either a
+ * function or as a macro defined to NULL.
+ */
 # define VIR_CLASS_NEW(name, prnt) \
     verify_expr(offsetof(name, parent) == 0, \
       (name##Class = virClassNew(prnt, #name, sizeof(name), name##Dispose)))