Re: [PATCH v7 17/65] qom: add object_{class_}property_add_qapi_enum

[Markus Armbruster <armbru@xxxxxxxxxx>]

Marc-André Lureau <marcandre.lureau@xxxxxxxxxx> writes:

> Signed-off-by: Markus Armbruster <armbru@xxxxxxxxxx>
> Signed-off-by: Marc-André Lureau <marcandre.lureau@xxxxxxxxxx>
> ---
>  include/qom/object.h | 74 ++++++++++++++++++++++++++++++++++++++++++
>  qom/object.c         | 90 
> +++++++++++++++++++++++++++++++++++++++++++++++++---
>  2 files changed, 159 insertions(+), 5 deletions(-)
>
> diff --git a/include/qom/object.h b/include/qom/object.h
> index eb61d8842b80..e04be4caed57 100644
> --- a/include/qom/object.h
> +++ b/include/qom/object.h
> @@ -2027,6 +2027,80 @@ ObjectProperty 
> *object_class_property_add_enum(ObjectClass *klass,
>                                      int (*get)(Object *, Error **),
>                                      void (*set)(Object *, int, Error **));
>  
> +/**
> + * struct QapiEnumProp: Descriptor for a property backed by a QAPI enum type
> + *
> + * Binds a QOM object property to a QAPI enum, providing automatic
> + * string<->int conversion through QAPI visitors and optional
> + * default-value initialization during object instance init.
> + *
> + * Use the QAPI_ENUM_PROP() macro to construct instances inline.
> + *
> + * @name: property name exposed on the QOM object
> + * @description: human-readable description (shown in ``-device help``, etc.)
> + * @default_value: initial enum value applied via @set during instance init,
> + *                 or -1 (the QAPI_ENUM_PROP default) to skip initialization
> + * @qapi_type: pointer to the generated QAPITypeInfo for the enum
> + *             (provides the string<->int lookup table)
> + * @get: getter that returns the current enum value as int, or -1 on error
> + * @set: setter that receives the enum value as int; %NULL for read-only 
> props
> + */
> +typedef struct QapiEnumProp {
> +    const char *name;
> +    const char *description;
> +    const int default_value;
> +    const QAPITypeInfo *qapi_type;
> +    int (*get)(Object *, Error **);
> +    void (*set)(Object *, int, Error **);
> +} QapiEnumProp;
> +
> +#define QAPI_ENUM_PROP(...) ({                                           \
> +    static const QapiEnumProp _prop = {                                  \
> +        .default_value = -1, __VA_ARGS__                                 \
> +    };                                                                   \
> +    &_prop; })

This is a cute and reasonably well-known macro trick for optional
keyword arguments in C.

The example [*] below specifies all arguments.  What happens when we
omit any?  They default to zero via default initializaion, except for
.default_value, which defaults to -1.

Trap for developers: some arguments aren't actually optional!  If you
forget to specify @name or @qapi_type, the code compiles, but crashes at
run time.

Not a fan.

> +
> +/**
> + * object_property_add_qapi_enum:
> + * @obj: the object to add a property to
> + * @prop: property descriptor
> + *
> + * Add an enum property with QAPI type association.
> + *
> + * Returns: The newly added property on success, or %NULL on failure.
> + */
> +ObjectProperty *
> +object_property_add_qapi_enum(Object *obj, const QapiEnumProp *prop);
> +
> +/**
> + * object_class_property_add_qapi_enum:
> + * @klass: the class object to add a property to
> + * @prop: property descriptor
> + *
> + * Add an enum property with QAPI type association.
> + *
> + * Use the QAPI_ENUM_PROP() macro to construct the property descriptor
> + * inline. If .default_value is not set, the property is not initialized
> + * (default_value is -1). Otherwise, the setter is called with
> + * default_value during object instance init.
> + *
> + * Example::

[*]

> + *
> + *   object_class_property_add_qapi_enum(oc, QAPI_ENUM_PROP(
> + *       .name = "policy",
> + *       .description = "Set the NUMA policy",
> + *       .default_value = HOST_MEM_POLICY_DEFAULT,
> + *       .qapi_type = &HostMemPolicy_type_info,
> + *       .get = my_get_policy,
> + *       .set = my_set_policy,
> + *   ));
> + *
> + * Returns: The newly added property on success, or %NULL on failure.
> + */
> +ObjectProperty *
> +object_class_property_add_qapi_enum(ObjectClass *klass,
> +                                    const QapiEnumProp *prop);
> +
>  /**
>   * object_property_add_qapi:
>   * @obj: the object to add a property to

[...]