Introduce object_class_property_deprecate() to register
a QOM property as deprecated. When this property's getter /
setter is called, a deprecation warning is displayed on the
monitor.

Inspired-by: Daniel P. Berrange <berrange@redhat.com>
Signed-off-by: Philippe Mathieu-Daudé <philmd@linaro.org>
---
 include/qom/object.h | 17 +++++++++++++++++
 qom/object.c         | 23 +++++++++++++++++++++++
 2 files changed, 40 insertions(+)

diff --git a/include/qom/object.h b/include/qom/object.h
index ef7258a5e1..b76724292c 100644
--- a/include/qom/object.h
+++ b/include/qom/object.h
@@ -97,6 +97,7 @@ struct ObjectProperty
     ObjectPropertyInit *init;
     void *opaque;
     QObject *defval;
+    const char *deprecation_reason;
 };
 
 /**
@@ -1075,6 +1076,22 @@ ObjectProperty *object_class_property_add(ObjectClass *klass, const char *name,
                                           ObjectPropertyRelease *release,
                                           void *opaque);
 
+/**
+ * object_class_property_deprecate:
+ * @klass: the class to add a property to
+ * @name: the name of the property.  This can contain any character except for
+ *  a forward slash.  In general, you should use hyphens '-' instead of
+ *  underscores '_' when naming properties.
+ * @reason: the deprecation reason.
+ * @version_major: the major version since this property is deprecated.
+ * @version_minor: the minor version since this property is deprecated.
+ *
+ * Deprecate a class property.
+ */
+void object_class_property_deprecate(ObjectClass *klass,
+                                     const char *name, const char *reason,
+                                     int version_major, int version_minor);
+
 /**
  * object_property_set_default_bool:
  * @prop: the property to set
diff --git a/qom/object.c b/qom/object.c
index e25f1e96db..05b97cd424 100644
--- a/qom/object.c
+++ b/qom/object.c
@@ -1293,6 +1293,16 @@ object_class_property_add(ObjectClass *klass,
     return prop;
 }
 
+void object_class_property_deprecate(ObjectClass *klass,
+                                     const char *name, const char *reason,
+                                     int version_major, int version_minor)
+{
+    ObjectProperty *prop = object_class_property_find(klass, name);
+
+    assert(prop);
+    prop->deprecation_reason = reason;
+}
+
 ObjectProperty *object_property_find(Object *obj, const char *name)
 {
     ObjectProperty *prop;
@@ -1382,6 +1392,17 @@ void object_property_del(Object *obj, const char *name)
     g_hash_table_remove(obj->properties, name);
 }
 
+static void object_property_check_deprecation(const Object *obj,
+                                              const char *name,
+                                              const ObjectProperty *prop)
+{
+    if (!prop->deprecation_reason) {
+        return;
+    }
+    warn_report("Property '%s.%s' is deprecated (%s).",
+                object_get_typename(obj), name, prop->deprecation_reason);
+}
+
 bool object_property_get(Object *obj, const char *name, Visitor *v,
                          Error **errp)
 {
@@ -1392,6 +1413,7 @@ bool object_property_get(Object *obj, const char *name, Visitor *v,
         return false;
     }
 
+    object_property_check_deprecation(obj, name, prop);
     if (!prop->get) {
         error_setg(errp, "Property '%s.%s' is not readable",
                    object_get_typename(obj), name);
@@ -1412,6 +1434,7 @@ bool object_property_set(Object *obj, const char *name, Visitor *v,
         return false;
     }
 
+    object_property_check_deprecation(obj, name, prop);
     if (!prop->set) {
         error_setg(errp, "Property '%s.%s' is not writable",
                    object_get_typename(obj), name);
-- 
2.38.1

On Mon, Jan 09, 2023 at 11:54:16PM +0100, Philippe Mathieu-Daudé wrote:
> Introduce object_class_property_deprecate() to register
> a QOM property as deprecated. When this property's getter /
> setter is called, a deprecation warning is displayed on the
> monitor.
> 
> Inspired-by: Daniel P. Berrange <berrange@redhat.com>
> Signed-off-by: Philippe Mathieu-Daudé <philmd@linaro.org>
> ---
>  include/qom/object.h | 17 +++++++++++++++++
>  qom/object.c         | 23 +++++++++++++++++++++++
>  2 files changed, 40 insertions(+)
> 
> diff --git a/include/qom/object.h b/include/qom/object.h
> index ef7258a5e1..b76724292c 100644
> --- a/include/qom/object.h
> +++ b/include/qom/object.h
> @@ -97,6 +97,7 @@ struct ObjectProperty
>      ObjectPropertyInit *init;
>      void *opaque;
>      QObject *defval;
> +    const char *deprecation_reason;
>  };
>  
>  /**
> @@ -1075,6 +1076,22 @@ ObjectProperty *object_class_property_add(ObjectClass *klass, const char *name,
>                                            ObjectPropertyRelease *release,
>                                            void *opaque);
>  
> +/**
> + * object_class_property_deprecate:
> + * @klass: the class to add a property to
> + * @name: the name of the property.  This can contain any character except for
> + *  a forward slash.  In general, you should use hyphens '-' instead of
> + *  underscores '_' when naming properties.
> + * @reason: the deprecation reason.
> + * @version_major: the major version since this property is deprecated.
> + * @version_minor: the minor version since this property is deprecated.
> + *
> + * Deprecate a class property.
> + */
> +void object_class_property_deprecate(ObjectClass *klass,
> +                                     const char *name, const char *reason,
> +                                     int version_major, int version_minor);
> +
>  /**
>   * object_property_set_default_bool:
>   * @prop: the property to set
> diff --git a/qom/object.c b/qom/object.c
> index e25f1e96db..05b97cd424 100644
> --- a/qom/object.c
> +++ b/qom/object.c
> @@ -1293,6 +1293,16 @@ object_class_property_add(ObjectClass *klass,
>      return prop;
>  }
>  
> +void object_class_property_deprecate(ObjectClass *klass,
> +                                     const char *name, const char *reason,
> +                                     int version_major, int version_minor)
> +{
> +    ObjectProperty *prop = object_class_property_find(klass, name);
> +
> +    assert(prop);
> +    prop->deprecation_reason = reason;
> +}

Nothing is using the 'version_major' / 'version_minor' parameters so
they look redundant.

> @@ -1392,6 +1413,7 @@ bool object_property_get(Object *obj, const char *name, Visitor *v,
>          return false;
>      }
>  
> +    object_property_check_deprecation(obj, name, prop);
>      if (!prop->get) {
>          error_setg(errp, "Property '%s.%s' is not readable",
>                     object_get_typename(obj), name);
> @@ -1412,6 +1434,7 @@ bool object_property_set(Object *obj, const char *name, Visitor *v,
>          return false;
>      }
>  
> +    object_property_check_deprecation(obj, name, prop);
>      if (!prop->set) {
>          error_setg(errp, "Property '%s.%s' is not writable",
>                     object_get_typename(obj), name);
> -- 
> 2.38.1
> 

With regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|

On Mon, Jan 09, 2023 at 11:54:16PM +0100, Philippe Mathieu-Daudé wrote:
> Introduce object_class_property_deprecate() to register
> a QOM property as deprecated. When this property's getter /
> setter is called, a deprecation warning is displayed on the
> monitor.
> 
> Inspired-by: Daniel P. Berrange <berrange@redhat.com>
> Signed-off-by: Philippe Mathieu-Daudé <philmd@linaro.org>
> ---
>  include/qom/object.h | 17 +++++++++++++++++
>  qom/object.c         | 23 +++++++++++++++++++++++
>  2 files changed, 40 insertions(+)
> 
> diff --git a/include/qom/object.h b/include/qom/object.h
> index ef7258a5e1..b76724292c 100644
> --- a/include/qom/object.h
> +++ b/include/qom/object.h
> @@ -97,6 +97,7 @@ struct ObjectProperty
>      ObjectPropertyInit *init;
>      void *opaque;
>      QObject *defval;
> +    const char *deprecation_reason;
>  };

qapi/qom.list should change ObjectPropertyInfo type to
include a 'deprecated': 'bool'  field, as we've done
for machine types and CPU models. Then qmp_qom_list
should set this flag  "deprecated = !!deprecation_reason"


With regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|