[libvirt] [PATCH 1/4] util: object: Note that VIR_AUTOUNREF variables must have the reference

[Peter Krempa]

When a pointer is assigned to a variable marked by VIR_AUTOUNREF it will
be unref'd when the stack frame of the variable is destroyed and thus
users must assign it only when they wish to shed the reference. Add this
as a note to the VIR_AUTOUNREF macro.

Signed-off-by: Peter Krempa <pkrempa at redhat.com>
---
 src/util/virobject.h | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/src/util/virobject.h b/src/util/virobject.h
index fe5dbe7326..6fca4cd166 100644
--- a/src/util/virobject.h
+++ b/src/util/virobject.h
@@ -117,7 +117,9 @@ virObjectAutoUnref(void *objptr);
  * @type: type of an virObject subclass to be unref'd automatically
  *
  * Declares a variable of @type which will be automatically unref'd when
- * control goes out of the scope.
+ * control goes out of the scope. The object referenced by the pointer assigned
+ * to the variable declared by this macro must already have the reference
+ * counter increased at the time of assignment.
  */
 #define VIR_AUTOUNREF(type) \
     __attribute__((cleanup(virObjectAutoUnref))) type
-- 
2.21.0