[RFC 3/7] qom: deprecate use of instance properties

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

The concept of class properties was introduced over 10 years ago.
While there is significant use of class properties, there is a
long way to go before any conversion is complete and new uses are
often introduced as it is not obvious that class properties are
preferred.

The downsides of instances properties are:

 * Increased memory usage as the property info is duplicated
   across every instance.

 * Introspection side effects, since instances need to be created
   to be introspected and this can have unexpected side effects
   if code is not expecting these throwaway instances to be
   around.

 * Non-introspectable designs, if properties are conditionally
   registered against instances, those props may not be visible
   when a dummy instances is created for introspection.

This deprecates the use of instance properties for all regular
scalar properties. ie strings, integers, enums, etc.

It does not deprecate instance properties used for setting up
the QOM composition tree child relationships, nor the link or
alias properties.

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

diff --git a/include/qom/object.h b/include/qom/object.h
index dd708b1136..e9ce15d595 100644
--- a/include/qom/object.h
+++ b/include/qom/object.h
@@ -1175,6 +1175,10 @@ void object_unref(void *obj);
  * @opaque: an opaque pointer to pass to the callbacks for the property
  * @errp: pointer to error object
  *
+ * Use of this function is now deprecated. All properties must be
+ * registered against the class, using the object_class_property_add()
+ * function and not registered against instances.
+ *
  * Returns: The #ObjectProperty; this can be used to set the @resolve
  * callback for child and link properties.
  */
@@ -1183,7 +1187,8 @@ ObjectProperty *object_property_try_add(Object *obj, const char *name,
                                         ObjectPropertyAccessor *get,
                                         ObjectPropertyAccessor *set,
                                         ObjectPropertyRelease *release,
-                                        void *opaque, Error **errp);
+                                        void *opaque, Error **errp)
+    QEMU_DEPRECATED;
 
 /**
  * object_property_add:
@@ -1206,13 +1211,18 @@ ObjectProperty *object_property_try_add(Object *obj, const char *name,
  *   meant to allow a property to free its opaque upon object
  *   destruction.  This may be NULL.
  * @opaque: an opaque pointer to pass to the callbacks for the property
+ *
+ * Use of this function is now deprecated. All properties must be
+ * registered against the class, using the object_class_property_add()
+ * function and not registered against instances.
  */
 ObjectProperty *object_property_add(Object *obj, const char *name,
                                     const char *type,
                                     ObjectPropertyAccessor *get,
                                     ObjectPropertyAccessor *set,
                                     ObjectPropertyRelease *release,
-                                    void *opaque);
+                                    void *opaque)
+    QEMU_DEPRECATED;
 
 void object_property_del(Object *obj, const char *name);
 
@@ -1873,11 +1883,16 @@ Object *object_resolve_and_typecheck(const char *path, const char *name,
  * Add a string property using getters/setters.  This function will add a
  * property of type 'string'.
  *
+ * Use of this function is now deprecated. All properties must be
+ * registered against the class, using the object_class_property_add_str()
+ * function and not registered against instances.
+ *
  * Returns: The newly added property on success, or %NULL on failure.
  */
 ObjectProperty *object_property_add_str(Object *obj, const char *name,
                              char *(*get)(Object *, Error **),
-                             void (*set)(Object *, const char *, Error **));
+                             void (*set)(Object *, const char *, Error **))
+    QEMU_DEPRECATED;
 
 ObjectProperty *object_class_property_add_str(ObjectClass *klass,
                                    const char *name,
@@ -1895,11 +1910,16 @@ ObjectProperty *object_class_property_add_str(ObjectClass *klass,
  * Add a bool property using getters/setters.  This function will add a
  * property of type 'bool'.
  *
+ * Use of this function is now deprecated. All properties must be
+ * registered against the class, using the object_class_property_add_bool()
+ * function and not registered against instances.
+ *
  * Returns: The newly added property on success, or %NULL on failure.
  */
 ObjectProperty *object_property_add_bool(Object *obj, const char *name,
                               bool (*get)(Object *, Error **),
-                              void (*set)(Object *, bool, Error **));
+                              void (*set)(Object *, bool, Error **))
+    QEMU_DEPRECATED;
 
 ObjectProperty *object_class_property_add_bool(ObjectClass *klass,
                                     const char *name,
@@ -1918,13 +1938,18 @@ ObjectProperty *object_class_property_add_bool(ObjectClass *klass,
  * Add an enum property using getters/setters.  This function will add a
  * property of type '@typename'.
  *
+ * Use of this function is now deprecated. All properties must be
+ * registered against the class, using the object_class_property_add_enum()
+ * function and not registered against instances.
+ *
  * Returns: The newly added property on success, or %NULL on failure.
  */
 ObjectProperty *object_property_add_enum(Object *obj, const char *name,
                               const char *typename,
                               const QEnumLookup *lookup,
                               int (*get)(Object *, Error **),
-                              void (*set)(Object *, int, Error **));
+                              void (*set)(Object *, int, Error **))
+    QEMU_DEPRECATED;
 
 ObjectProperty *object_class_property_add_enum(ObjectClass *klass,
                                     const char *name,
@@ -1942,10 +1967,15 @@ ObjectProperty *object_class_property_add_enum(ObjectClass *klass,
  * Add a read-only struct tm valued property using a getter function.
  * This function will add a property of type 'struct tm'.
  *
+ * Use of this function is now deprecated. All properties must be
+ * registered against the class, using the object_class_property_add_tm()
+ * function and not registered against instances.
+ *
  * Returns: The newly added property on success, or %NULL on failure.
  */
 ObjectProperty *object_property_add_tm(Object *obj, const char *name,
-                            void (*get)(Object *, struct tm *, Error **));
+                            void (*get)(Object *, struct tm *, Error **))
+    QEMU_DEPRECATED;
 
 ObjectProperty *object_class_property_add_tm(ObjectClass *klass,
                             const char *name,
@@ -1970,11 +2000,16 @@ typedef enum {
  * Add an integer property in memory.  This function will add a
  * property of type 'uint8'.
  *
+ * Use of this function is now deprecated. All properties must be
+ * registered against the class, using the object_class_property_add_uint8_ptr()
+ * function and not registered against instances.
+ *
  * Returns: The newly added property on success, or %NULL on failure.
  */
 ObjectProperty *object_property_add_uint8_ptr(Object *obj, const char *name,
                                               const uint8_t *v,
-                                              ObjectPropertyFlags flags);
+                                              ObjectPropertyFlags flags)
+    QEMU_DEPRECATED;
 
 ObjectProperty *object_class_property_add_uint8_ptr(ObjectClass *klass,
                                          const char *name,
@@ -1991,11 +2026,16 @@ ObjectProperty *object_class_property_add_uint8_ptr(ObjectClass *klass,
  * Add an integer property in memory.  This function will add a
  * property of type 'uint16'.
  *
+ * Use of this function is now deprecated. All properties must be
+ * registered against the class, using the object_class_property_add_uint16_ptr()
+ * function and not registered against instances.
+ *
  * Returns: The newly added property on success, or %NULL on failure.
  */
 ObjectProperty *object_property_add_uint16_ptr(Object *obj, const char *name,
                                     const uint16_t *v,
-                                    ObjectPropertyFlags flags);
+                                    ObjectPropertyFlags flags)
+    QEMU_DEPRECATED;
 
 ObjectProperty *object_class_property_add_uint16_ptr(ObjectClass *klass,
                                           const char *name,
@@ -2012,11 +2052,16 @@ ObjectProperty *object_class_property_add_uint16_ptr(ObjectClass *klass,
  * Add an integer property in memory.  This function will add a
  * property of type 'uint32'.
  *
+ * Use of this function is now deprecated. All properties must be
+ * registered against the class, using the object_class_property_add_uint32_ptr()
+ * function and not registered against instances.
+ *
  * Returns: The newly added property on success, or %NULL on failure.
  */
 ObjectProperty *object_property_add_uint32_ptr(Object *obj, const char *name,
                                     const uint32_t *v,
-                                    ObjectPropertyFlags flags);
+                                    ObjectPropertyFlags flags)
+    QEMU_DEPRECATED;
 
 ObjectProperty *object_class_property_add_uint32_ptr(ObjectClass *klass,
                                           const char *name,
@@ -2033,11 +2078,16 @@ ObjectProperty *object_class_property_add_uint32_ptr(ObjectClass *klass,
  * Add an integer property in memory.  This function will add a
  * property of type 'uint64'.
  *
+ * Use of this function is now deprecated. All properties must be
+ * registered against the class, using the object_class_property_add_uint64_ptr()
+ * function and not registered against instances.
+ *
  * Returns: The newly added property on success, or %NULL on failure.
  */
 ObjectProperty *object_property_add_uint64_ptr(Object *obj, const char *name,
                                     const uint64_t *v,
-                                    ObjectPropertyFlags flags);
+                                    ObjectPropertyFlags flags)
+    QEMU_DEPRECATED;
 
 ObjectProperty *object_class_property_add_uint64_ptr(ObjectClass *klass,
                                           const char *name,
diff --git a/qom/object.c b/qom/object.c
index 33b2801ee4..415d5c5291 100644
--- a/qom/object.c
+++ b/qom/object.c
@@ -1362,8 +1362,10 @@ object_property_try_add(Object *obj, const char *name, const char *type,
         for (i = 0; i < INT16_MAX; ++i) {
             char *full_name = g_strdup_printf("%s[%d]", name_no_array, i);
 
+            QEMU_DEPRECATIONS_OFF;
             ret = object_property_try_add(obj, full_name, type, get, set,
                                           release, opaque, NULL);
+            QEMU_DEPRECATIONS_ON;
             g_free(full_name);
             if (ret) {
                 break;
@@ -1403,8 +1405,10 @@ object_property_add(Object *obj, const char *name, const char *type,
                     ObjectPropertyRelease *release,
                     void *opaque)
 {
+    QEMU_DEPRECATIONS_OFF;
     return object_property_try_add(obj, name, type, get, set, release,
                                    opaque, &error_abort);
+    QEMU_DEPRECATIONS_ON;
 }
 
 ObjectProperty *
@@ -1951,9 +1955,11 @@ object_property_try_add_child(Object *obj, const char *name,
 
     type = g_strdup_printf("child<%s>", object_get_typename(child));
 
+    QEMU_DEPRECATIONS_OFF;
     op = object_property_try_add(obj, name, type, object_get_child_property,
                                  NULL, object_finalize_child_property,
                                  child, errp);
+    QEMU_DEPRECATIONS_ON;
     if (!op) {
         return NULL;
     }
@@ -1967,7 +1973,9 @@ ObjectProperty *
 object_property_add_child(Object *obj, const char *name,
                           Object *child)
 {
+    QEMU_DEPRECATIONS_OFF;
     return object_property_try_add_child(obj, name, child, &error_abort);
+    QEMU_DEPRECATIONS_ON;
 }
 
 void object_property_allow_set_link(const Object *obj, const char *name,
@@ -2145,11 +2153,13 @@ object_add_link_prop(Object *obj, const char *name,
 
     full_type = g_strdup_printf("link<%s>", type);
 
+    QEMU_DEPRECATIONS_OFF;
     op = object_property_add(obj, name, full_type,
                              object_get_link_property,
                              check ? object_set_link_property : NULL,
                              object_release_link_property,
                              prop);
+    QEMU_DEPRECATIONS_ON;
     op->resolve = object_resolve_link_property;
     return op;
 }
@@ -2442,11 +2452,13 @@ object_property_add_str(Object *obj, const char *name,
     prop->get = get;
     prop->set = set;
 
+    QEMU_DEPRECATIONS_OFF;
     return object_property_add(obj, name, "string",
                                get ? property_get_str : NULL,
                                set ? property_set_str : NULL,
                                property_release_data,
                                prop);
+    QEMU_DEPRECATIONS_ON;
 }
 
 ObjectProperty *
@@ -2512,11 +2524,13 @@ object_property_add_bool(Object *obj, const char *name,
     prop->get = get;
     prop->set = set;
 
+    QEMU_DEPRECATIONS_OFF;
     return object_property_add(obj, name, "bool",
                                get ? property_get_bool : NULL,
                                set ? property_set_bool : NULL,
                                property_release_data,
                                prop);
+    QEMU_DEPRECATIONS_ON;
 }
 
 ObjectProperty *
@@ -2577,11 +2591,13 @@ object_property_add_enum(Object *obj, const char *name,
     prop->get = get;
     prop->set = set;
 
+    QEMU_DEPRECATIONS_OFF;
     return object_property_add(obj, name, typename,
                                get ? property_get_enum : NULL,
                                set ? property_set_enum : NULL,
                                property_release_data,
                                prop);
+    QEMU_DEPRECATIONS_ON;
 }
 
 ObjectProperty *
@@ -2655,10 +2671,12 @@ object_property_add_tm(Object *obj, const char *name,
 
     prop->get = get;
 
+    QEMU_DEPRECATIONS_OFF;
     return object_property_add(obj, name, "struct tm",
                                get ? property_get_tm : NULL, NULL,
                                property_release_data,
                                prop);
+    QEMU_DEPRECATIONS_ON;
 }
 
 ObjectProperty *
@@ -2775,8 +2793,10 @@ object_property_add_uint8_ptr(Object *obj, const char *name,
         setter = property_set_uint8_ptr;
     }
 
+    QEMU_DEPRECATIONS_OFF;
     return object_property_add(obj, name, "uint8",
                                getter, setter, NULL, (void *)v);
+    QEMU_DEPRECATIONS_ON;
 }
 
 ObjectProperty *
@@ -2815,8 +2835,10 @@ object_property_add_uint16_ptr(Object *obj, const char *name,
         setter = property_set_uint16_ptr;
     }
 
+    QEMU_DEPRECATIONS_OFF;
     return object_property_add(obj, name, "uint16",
                                getter, setter, NULL, (void *)v);
+    QEMU_DEPRECATIONS_ON;
 }
 
 ObjectProperty *
@@ -2855,8 +2877,10 @@ object_property_add_uint32_ptr(Object *obj, const char *name,
         setter = property_set_uint32_ptr;
     }
 
+    QEMU_DEPRECATIONS_OFF;
     return object_property_add(obj, name, "uint32",
                                getter, setter, NULL, (void *)v);
+    QEMU_DEPRECATIONS_ON;
 }
 
 ObjectProperty *
@@ -2895,8 +2919,10 @@ object_property_add_uint64_ptr(Object *obj, const char *name,
         setter = property_set_uint64_ptr;
     }
 
+    QEMU_DEPRECATIONS_OFF;
     return object_property_add(obj, name, "uint64",
                                getter, setter, NULL, (void *)v);
+    QEMU_DEPRECATIONS_ON;
 }
 
 ObjectProperty *
@@ -2983,11 +3009,13 @@ object_property_add_alias(Object *obj, const char *name,
     prop->target_obj = target_obj;
     prop->target_name = g_strdup(target_name);
 
+    QEMU_DEPRECATIONS_OFF;
     op = object_property_add(obj, name, prop_type,
                              property_get_alias,
                              property_set_alias,
                              property_release_alias,
                              prop);
+    QEMU_DEPRECATIONS_ON;
     op->resolve = property_resolve_alias;
     if (target_prop->defval) {
         op->defval = qobject_ref(target_prop->defval);
-- 
2.54.0