Re: [PATCH 2/4] qom: provide convenient macros for declaring and defining types

[Eric Blake]

On 7/23/20 1:14 PM, Daniel P. Berrangé wrote:
> When creating new QOM types, there is a lot of boilerplate code that
> must be repeated using a standard pattern. This is tedious to write
> and liable to suffer from subtle inconsistencies. Thus it would
> benefit from some simple automation.
>
> QOM was loosely inspired by GLib's GObject, and indeed GObject suffers
> from the same burden of boilerplate code, but has long provided a set of
> macros to eliminate this burden in the source implementation. More
> recently it has also provided a set of macros to eliminate this burden
> in the header declaration.
>
> In GLib there are the G_DECLARE_* and G_DEFINE_* family of macros
> for the header declaration and source implementation respectively:
>
>    https://developer.gnome.org/gobject/stable/chapter-gobject.html
>    https://developer.gnome.org/gobject/stable/howto-gobject.html
>
> This patch takes inspiration from GObject to provide the equivalent
> functionality for QOM.

> IOW, in both cases the maintainer now only has to think about the
> interesting part of the code which implements useful functionality
> and avoids much of the boilerplate.
>
> Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
> ---
>   include/qom/object.h | 277 +++++++++++++++++++++++++++++++++++++++++++
>   1 file changed, 277 insertions(+)
>
> diff --git a/include/qom/object.h b/include/qom/object.h
> index 1f8aa2d48e..be64421089 100644
> --- a/include/qom/object.h
> +++ b/include/qom/object.h
> @@ -304,6 +304,119 @@ typedef struct InterfaceInfo InterfaceInfo;
>    *
>    * The first example of such a QOM method was #CPUClass.reset,
>    * another example is #DeviceClass.realize.
> + *
> + * # Standard type declaration and definition macros #
> + *
> + * A lot of the code outlined above follows a standard pattern and naming
> + * convention. To reduce the amount of boilerplate code that needs to be
> + * written for a new type there are two sets of macros to generate the
> + * common parts in a standard format.
> + *
> + * A type is declared using the OBJECT_DECLARE macro family. In types
> + * which do not require any virtual functions in the class, the
> + * OBJECT_DECLARE_SIMPLE_TYPE macro is suitable, and is commonly placed
> + * in the header file:
> + *
> + * <example>
> + *   <title>Declaring a simple type</title>
> + *   <programlisting>
> + *     OBJECT_DECLARE_SIMPLE_TYPE(MyDevice, my_device, MY_DEVICE, DEVICE)

How sensitive is this macro to trailing semicolon?  Must the user omit 
it (as shown here), supply it (by tweaking the macro to be a syntax 
error if one is not supplied), or is it optional?  I guess whatever glib 
does is fine to copy, though.

Hmm. I think you meant to use s/ DEVICE/ Device/ here...

> + *   </programlisting>
> + * </example>
> + *
> + * This is equivalent to the following:
> + *
> + * <example>
> + *   <title>Expansion from declaring a simple type</title>
> + *   <programlisting>
> + *     typedef struct MyDevice MyDevice;
> + *     typedef struct MyDeviceClass MyDeviceClass;
> + *
> + *     G_DEFINE_AUTOPTR_CLEANUP_FUNC(MyDeviceClass, object_unref)
> + *
> + *     #define MY_DEVICE_GET_CLASS(void *obj) \
> + *             OBJECT_GET_CLASS(MyDeviceClass, obj, TYPE_MY_DEVICE)

How'd you manage to invoke #define inside the OBJECT_DECLARE_SIMPLE_TYPE 
macro expansion?

/me reads ahead

Oh, you didn't; you used a static inline function instead.  But the 
effect is the same, so claiming the equivalence here, while slightly 
misleading, is not horrible.

> + *     #define MY_DEVICE_CLASS(void *klass) \
> + *             OBJECT_CLASS_CHECK(MyDeviceClass, klass, TYPE_MY_DEVICE)
> + *     #define MY_DEVICE(void *obj)
> + *             OBJECT_CHECK(MyDevice, obj, TYPE_MY_DEVICE)
> + *
> + *     struct MyDeviceClass {
> + *         DeviceClass parent_class;

...given that this line is constructed as arg4##Class, and the fact that 
we have DeviceClass, not DEVICEClass.

> + *     };
> + *   </programlisting>
> + * </example>
> + *
> + * The 'struct MyDevice' needs to be declared separately.
> + * If the type requires virtual functions to be declared in the class
> + * struct, then the alternative OBJECT_DECLARE_TYPE() macro can be
> + * used. This does the same as OBJECT_DECLARE_SIMPLE_TYPE(), but without
> + * the 'struct MyDeviceClass' definition.
> + *
> + * To implement the type, the OBJECT_DEFINE macro family is available.
> + * In the simple case the OBJECT_DEFINE_TYPE macro is suitable:
> + *
> + * <example>
> + *   <title>Defining a simple type</title>
> + *   <programlisting>
> + *     OBJECT_DEFINE_TYPE(MyDevice, my_device, MY_DEVICE, DEVICE)

Unlike the declare, here, using DEVICE looks correct...

> + *   </programlisting>
> + * </example>
> + *
> + * This is equivalent to the following:
> + *
> + * <example>
> + *   <title>Expansion from defining a simple type</title>
> + *   <programlisting>
> + *     static void my_device_finalize(Object *obj);
> + *     static void my_device_class_init(ObjectClass *oc, void *data);
> + *     static void my_device_init(Object *obj);
> + *
> + *     static const TypeInfo my_device_info = {
> + *         .parent = TYPE_DEVICE,

...given the expansion here.

> + *         .name = TYPE_MY_DEVICE,
> + *         .instance_size = sizeof(MyDevice),
> + *         .instance_init = my_device_init,
> + *         .instance_finalize = my_device_finalize,
> + *         .class_size = sizeof(MyDeviceClass),
> + *         .class_init = my_device_class_init,
> + *     };
> + *
> + *     static void
> + *     my_device_register_types(void)
> + *     {
> + *         type_register_static(&my_device_info);
> + *     }
> + *     type_init(my_device_register_types);
> + *   </programlisting>
> + * </example>
> + *
> + * This is sufficient to get the type registered with the type
> + * system, and the three standard methods now need to be implemented
> + * along with any other logic required for the type.
> + *
> + * If the type needs to implement one or more interfaces, then the
> + * OBJECT_DEFINE_TYPE_WITH_INTERFACES() macro can be used instead.
> + * This accepts an array of interface type names.
> + *
> + * <example>
> + *   <title>Defining a simple type implementing interfaces</title>
> + *   <programlisting>
> + *     OBJECT_DEFINE_TYPE_WITH_INTERFACES(MyDevice, my_device,
> + *                                        MY_DEVICE, DEVICE,
> + *                                        { TYPE_USER_CREATABLE }, { NULL })
> + *   </programlisting>
> + * </example>
> + *
> + * If the type is not intended to be instantiated, then then
> + * the OBJECT_DEFINE_ABSTRACT_TYPE() macro can be used instead:
> + *
> + * <example>
> + *   <title>Defining a simple type</title>

This title should probably mention 'abstract'.

> + *   <programlisting>
> + *     OBJECT_DEFINE_ABSTRACT_TYPE(MyDevice, my_device, MY_DEVICE, DEVICE)
> + *   </programlisting>
> + * </example>
>    */
>   
>   
> @@ -440,6 +553,170 @@ struct Object
>       Object *parent;
>   };
>   
> +/**
> + * OBJECT_DECLARE_TYPE:
> + * @ModuleObjName: the object name with initial capitalization
> + * @module_obj_name: the object name in lowercase with underscore separators
> + * @MODULE_OBJ_NAME: the object name in uppercase with underscore separators
> + *
> + * This macro is typically used in a header file, and will:
> + *
> + *   - create the typedefs for the object and class structs
> + *   - register the type for use with g_autoptr
> + *   - provide three standard type cast functions
> + *
> + * The object struct and class struct need to be declared manually.
> + */
> +#define OBJECT_DECLARE_TYPE(ModuleObjName, module_obj_name, MODULE_OBJ_NAME) \
> +    typedef struct ModuleObjName ModuleObjName; \
> +    typedef struct ModuleObjName##Class ModuleObjName##Class; \
> +    \
> +    G_DEFINE_AUTOPTR_CLEANUP_FUNC(ModuleObjName##Class, object_unref) \
> +    \
> +    static inline G_GNUC_UNUSED ModuleObjName##Class * \
> +    MODULE_OBJ_NAME##_GET_CLASS(void *obj) \
> +    { return OBJECT_GET_CLASS(ModuleObjName##Class, obj, \
> +                              TYPE_##MODULE_OBJ_NAME); } \
> +    \
> +    static inline G_GNUC_UNUSED ModuleObjName##Class * \
> +    MODULE_OBJ_NAME##_CLASS(void *klass) \
> +    { return OBJECT_CLASS_CHECK(ModuleObjName##Class, klass, \
> +                                TYPE_##MODULE_OBJ_NAME); } \
> +    \
> +    static inline G_GNUC_UNUSED ModuleObjName * \
> +    MODULE_OBJ_NAME(void *obj) \
> +    { return OBJECT_CHECK(ModuleObjName, obj, \
> +                          TYPE_##MODULE_OBJ_NAME); }
> +
> +/**
> + * OBJECT_DECLARE_SIMPLE_TYPE:
> + * @ModuleObjName: the object name with initial caps
> + * @module_obj_name: the object name in lowercase with underscore separators
> + * @MODULE_OBJ_NAME: the object name in uppercase with underscore separators
> + * @ParentModuleObjName: the parent object name with initial caps
> + *
> + * This does the same as OBJECT_DECLARE_TYPE(), but also declares
> + * the class struct, thus only the object struct needs to be declare

declared

> + * manually.
> + *
> + * This macro should be used unless the class struct needs to have
> + * virtual methods declared.
> + */
> +#define OBJECT_DECLARE_SIMPLE_TYPE(ModuleObjName, module_obj_name, \
> +                                   MODULE_OBJ_NAME, ParentModuleObjName) \
> +    OBJECT_DECLARE_TYPE(ModuleObjName, module_obj_name, MODULE_OBJ_NAME) \
> +    struct ModuleObjName##Class { ParentModuleObjName##Class parent_class; };
> +
> +
> +/**
> + * OBJECT_DEFINE_TYPE_EXTENDED:
> + * @ModuleObjName: the object name with initial caps
> + * @module_obj_name: the object name in lowercase with underscore separators
> + * @MODULE_OBJ_NAME: the object name in uppercase with underscore separators
> + * @PARENT_MODULE_OBJ_NAME: the parent object name in uppercase with underscore
> + *                          separators
> + * @ABSTRACT: boolean flag to indicate whether the object can be instantiated
> + * @...: list of initializers for "InterfaceInfo" to declare implemented 
> interfaces
> + *
> + * This macro is typically used in a source file, and will:
> + *
> + *   - declare prototypes for _finalize, _class_init and _init methods
> + *   - declare the TypeInfo struct instance
> + *   - provide the constructor to register the type
> + *
> + * After using this macro, implementations of the _finalize, _class_init,
> + * and _init methods need to be written. Any of these can be zero-line
> + * no-op impls if no special logic is required for a given type.
> + *
> + * This macro should rarely be used, instead one of the more specialized
> + * macros is usually a better choice.
> + */
> +#define OBJECT_DEFINE_TYPE_EXTENDED(ModuleObjName, module_obj_name, \
> +                                    MODULE_OBJ_NAME, PARENT_MODULE_OBJ_NAME, \
> +                                    ABSTRACT, ...) \
> +    static void \
> +    module_obj_name##_finalize(Object *obj); \
> +    static void \
> +    module_obj_name##_class_init(ObjectClass *oc, void *data); \
> +    static void \
> +    module_obj_name##_init(Object *obj); \
> +    \
> +    static const TypeInfo module_obj_name##_info = { \
> +        .parent = TYPE_##PARENT_MODULE_OBJ_NAME, \
> +        .name = TYPE_##MODULE_OBJ_NAME, \
> +        .instance_size = sizeof(ModuleObjName), \
> +        .instance_init = module_obj_name##_init, \
> +        .instance_finalize = module_obj_name##_finalize, \
> +        .class_size = sizeof(ModuleObjName##Class), \
> +        .class_init = module_obj_name##_class_init, \
> +        .abstract = ABSTRACT, \
> +        .interfaces = (InterfaceInfo[]) { __VA_ARGS__ } , \

Odd space before comma.

> +    }; \
> +    \
> +    static void \
> +    module_obj_name##_register_types(void) \
> +    { \
> +        type_register_static(&module_obj_name##_info); \
> +    } \
> +    type_init(module_obj_name##_register_types);
> +
> +/**
> + * OBJECT_DEFINE_TYPE:
> + * @ModuleObjName: the object name with initial caps
> + * @module_obj_name: the object name in lowercase with underscore separators
> + * @MODULE_OBJ_NAME: the object name in uppercase with underscore separators
> + * @PARENT_MODULE_OBJ_NAME: the parent object name in uppercase with underscore
> + *                          separators
> + *
> + * This is a specialization of OBJECT_DEFINE_TYPE_EXTENDED, which is suitable
> + * for the common case of a non-abstract type, without any interfaces.
> + */
> +#define OBJECT_DEFINE_TYPE(ModuleObjName, module_obj_name, MODULE_OBJ_NAME, \
> +                           PARENT_MODULE_OBJ_NAME) \
> +    OBJECT_DEFINE_TYPE_EXTENDED(ModuleObjName, module_obj_name, \
> +                                MODULE_OBJ_NAME, PARENT_MODULE_OBJ_NAME, \
> +                                false, { NULL })
> +
> +/**
> + * OBJECT_DEFINE_TYPE_WITH_INTERFACES:
> + * @ModuleObjName: the object name with initial caps
> + * @module_obj_name: the object name in lowercase with underscore separators
> + * @MODULE_OBJ_NAME: the object name in uppercase with underscore separators
> + * @PARENT_MODULE_OBJ_NAME: the parent object name in uppercase with underscore
> + *                          separators
> + * @...: list of initializers for "InterfaceInfo" to declare implemented 
> interfaces
> + *
> + * This is a specialization of OBJECT_DEFINE_TYPE_EXTENDED, which is suitable
> + * for the common case of a non-abstract type, with one or more implemented
> + * interfaces.
> + *
> + * Note when passing the list of interfaces, be sure to include the final
> + * NULL entry, e.g.  { TYPE_USER_CREATABLE }, { NULL }
> + */
> +#define OBJECT_DEFINE_TYPE_WITH_INTERFACES(ModuleObjName, module_obj_name, \
> +                                           MODULE_OBJ_NAME, \
> +                                           PARENT_MODULE_OBJ_NAME, ...) \
> +    OBJECT_DEFINE_TYPE_EXTENDED(ModuleObjName, module_obj_name, \
> +                                MODULE_OBJ_NAME, PARENT_MODULE_OBJ_NAME, \
> +                                false, __VA_ARGS__)
> +
> +/**
> + * OBJECT_DEFINE_ABSTRACT_TYPE:
> + * @ModuleObjName: the object name with initial caps
> + * @module_obj_name: the object name in lowercase with underscore separators
> + * @MODULE_OBJ_NAME: the object name in uppercase with underscore separators
> + * @PARENT_MODULE_OBJ_NAME: the parent object name in uppercase with underscore
> + *                          separators
> + *
> + * This is a specialization of OBJECT_DEFINE_TYPE_EXTENDED, which is suitable
> + * for defining an abstract type, without any interfaces.
> + */
> +#define OBJECT_DEFINE_ABSTRACT_TYPE(ModuleObjName, module_obj_name, \
> +                                    MODULE_OBJ_NAME, PARENT_MODULE_OBJ_NAME) \
> +    OBJECT_DEFINE_TYPE_EXTENDED(ModuleObjName, module_obj_name, \
> +                                MODULE_OBJ_NAME, PARENT_MODULE_OBJ_NAME, \
> +                                true, { NULL })
> +
>   /**
>    * TypeInfo:
>    * @name: The name of the type.

A couple minor spelling findings, but overall looks good.

Reviewed-by: Eric Blake <eblake@redhat.com>

--
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3226
Virtualization:  qemu.org | libvirt.org