[RFC 2/7] qom: deprecated embedding object structs within other objects

["Daniel P. Berrangé" <berrange@redhat.com>]

The QOM APIs currently allow objects to be either allocated directly
on the heap, or statically embedded inside the struct of another object.

For the latter QOM has logic to avoid calling 'free' on the object when
finalizers complete, however, this is not sufficient to make the
practice safe.

Users of QOM expect that if they call "object_ref" to acquire their own
reference, then object will never be freed as long as they hold it.

This expectation is broken when an instance is embedded, as the "owner"
object's may be finalized, which frees the memory that is storing the
embedded QOM instance, even if its ref-count is still live.

Worse still is that a user of a QOM object cannot easily tell if the
instance they're using is embedded or directly heap allocated.

Mark the APIs for embedding objects as deprecated as the first step
towards removal of this flawed design concept. All objects must now
be directly heap allocated going forward, and existing usage must be
incrementally converted.

Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
---
 include/qom/object.h | 28 ++++++++++++++++++++++++----
 qom/object.c         |  6 ++++++
 2 files changed, 30 insertions(+), 4 deletions(-)

diff --git a/include/qom/object.h b/include/qom/object.h
index 11f55613fc..dd708b1136 100644
--- a/include/qom/object.h
+++ b/include/qom/object.h
@@ -854,8 +854,13 @@ bool object_set_props_from_keyval(Object *obj, const QDict *qdict,
  * This function will initialize an object.  The memory for the object should
  * have already been allocated.  The returned object has a reference count of 1,
  * and will be finalized when the last reference is dropped.
+ *
+ * Use of this function is now deprecated. All objects must be
+ * allocated using the object_new() family of functions and not
+ * statically embedded in a larger struct.
  */
-void object_initialize(void *obj, size_t size, const char *typename);
+void object_initialize(void *obj, size_t size, const char *typename)
+    QEMU_DEPRECATED;
 
 /**
  * object_initialize_child_with_props:
@@ -873,6 +878,10 @@ void object_initialize(void *obj, size_t size, const char *typename);
  * has a reference count of 1 (for the "child<...>" property from the parent),
  * so the object will be finalized automatically when the parent gets removed.
  *
+ * Use of this function is now deprecated. All objects must be
+ * allocated using the object_new() family of functions and not
+ * statically embedded in a larger struct.
+ *
  * The variadic parameters are a list of pairs of (propname, propvalue)
  * strings. The propname of %NULL indicates the end of the property list.
  * If the object implements the user creatable interface, the object will
@@ -883,7 +892,8 @@ void object_initialize(void *obj, size_t size, const char *typename);
 bool object_initialize_child_with_props(Object *parentobj,
                              const char *propname,
                              void *childobj, size_t size, const char *type,
-                             Error **errp, ...) G_GNUC_NULL_TERMINATED;
+                             Error **errp, ...) G_GNUC_NULL_TERMINATED
+    QEMU_DEPRECATED;
 
 /**
  * object_initialize_child_with_propsv:
@@ -897,12 +907,17 @@ bool object_initialize_child_with_props(Object *parentobj,
  *
  * See object_initialize_child() for documentation.
  *
+ * Use of this function is now deprecated. All objects must be
+ * allocated using the object_new() family of functions and not
+ * statically embedded in a larger struct.
+ *
  * Returns: %true on success, %false on failure.
  */
 bool object_initialize_child_with_propsv(Object *parentobj,
                               const char *propname,
                               void *childobj, size_t size, const char *type,
-                              Error **errp, va_list vargs);
+                              Error **errp, va_list vargs)
+    QEMU_DEPRECATED;
 
 /**
  * object_initialize_child:
@@ -917,13 +932,18 @@ bool object_initialize_child_with_propsv(Object *parentobj,
  *   object_initialize_child_with_props(parent, propname,
  *                                      child, sizeof(*child), type,
  *                                      &error_abort, NULL)
+ *
+ * Use of this function is now deprecated. All objects must be
+ * allocated using the object_new() family of functions and not
+ * statically embedded in a larger struct.
  */
 #define object_initialize_child(parent, propname, child, type)          \
     object_initialize_child_internal((parent), (propname),              \
                                      (child), sizeof(*(child)), (type))
 void object_initialize_child_internal(Object *parent, const char *propname,
                                       void *child, size_t size,
-                                      const char *type);
+                                      const char *type)
+    QEMU_DEPRECATED;
 
 /**
  * object_dynamic_cast:
diff --git a/qom/object.c b/qom/object.c
index 0ac201de4c..33b2801ee4 100644
--- a/qom/object.c
+++ b/qom/object.c
@@ -522,9 +522,11 @@ bool object_initialize_child_with_props(Object *parentobj,
     bool ok;
 
     va_start(vargs, errp);
+QEMU_DEPRECATIONS_OFF;
     ok = object_initialize_child_with_propsv(parentobj, propname,
                                              childobj, size, type, errp,
                                              vargs);
+QEMU_DEPRECATIONS_ON;
     va_end(vargs);
     return ok;
 }
@@ -539,7 +541,9 @@ bool object_initialize_child_with_propsv(Object *parentobj,
     Object *obj;
     UserCreatable *uc;
 
+QEMU_DEPRECATIONS_OFF;
     object_initialize(childobj, size, type);
+QEMU_DEPRECATIONS_ON;
     obj = OBJECT(childobj);
 
     if (!object_set_propv(obj, vargs, errp)) {
@@ -576,8 +580,10 @@ void object_initialize_child_internal(Object *parent,
                                       void *child, size_t size,
                                       const char *type)
 {
+QEMU_DEPRECATIONS_OFF;
     object_initialize_child_with_props(parent, propname, child, size, type,
                                        &error_abort, NULL);
+QEMU_DEPRECATIONS_ON;
 }
 
 static inline bool object_property_is_child(ObjectProperty *prop)
-- 
2.54.0