qom: Consolidate OBJECT_{DEFINE|DECLARE}_SIMPLE_TYPE*

[PATCH 2/9] docs/devel/qom: Fix the doc about OBJECT_DECLARE_SIMPLE_TYPE

Posted by Zhao Liu 6 months ago

Currently, the expansion example of OBJECT_DECLARE_SIMPLE_TYPE "roughly"
reflects what OBJECT_DECLARE_TYPE is doing.

Why "roughly"? Because this line -

>    G_DEFINE_AUTOPTR_CLEANUP_FUNC(MyDeviceClass, object_unref)

- is also wrong for OBJECT_DECLARE_TYPE.

Fix the expansion example of OBJECT_DECLARE_SIMPLE_TYPE, especially
drop that definition of MyDeviceClass.

Cc: Paolo Bonzini <pbonzini@redhat.com>
Cc: "Daniel P. Berrangé" <berrange@redhat.com>
Cc: Eduardo Habkost <eduardo@habkost.net>
Signed-off-by: Zhao Liu <zhao1.liu@intel.com>
---
 docs/devel/qom.rst | 11 +----------
 1 file changed, 1 insertion(+), 10 deletions(-)

diff --git a/docs/devel/qom.rst b/docs/devel/qom.rst
index 5870745ba27b..185f4c2f5921 100644
--- a/docs/devel/qom.rst
+++ b/docs/devel/qom.rst
@@ -326,21 +326,12 @@ This is equivalent to the following:
    :caption: Expansion from declaring a simple type
 
    typedef struct MyDevice MyDevice;
-   typedef struct MyDeviceClass MyDeviceClass;
 
-   G_DEFINE_AUTOPTR_CLEANUP_FUNC(MyDeviceClass, object_unref)
+   G_DEFINE_AUTOPTR_CLEANUP_FUNC(MyDevice, object_unref)
 
-   #define MY_DEVICE_GET_CLASS(void *obj) \
-           OBJECT_GET_CLASS(MyDeviceClass, obj, TYPE_MY_DEVICE)
-   #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;
-   };
-
 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
-- 
2.34.1

Re: [PATCH 2/9] docs/devel/qom: Fix the doc about OBJECT_DECLARE_SIMPLE_TYPE

Posted by BALATON Zoltan 6 months ago

On Wed, 14 May 2025, Zhao Liu wrote:
> Currently, the expansion example of OBJECT_DECLARE_SIMPLE_TYPE "roughly"
> reflects what OBJECT_DECLARE_TYPE is doing.
>
> Why "roughly"? Because this line -
>
>>    G_DEFINE_AUTOPTR_CLEANUP_FUNC(MyDeviceClass, object_unref)
>
> - is also wrong for OBJECT_DECLARE_TYPE.
>
> Fix the expansion example of OBJECT_DECLARE_SIMPLE_TYPE, especially
> drop that definition of MyDeviceClass.
>
> Cc: Paolo Bonzini <pbonzini@redhat.com>
> Cc: "Daniel P. Berrangé" <berrange@redhat.com>
> Cc: Eduardo Habkost <eduardo@habkost.net>
> Signed-off-by: Zhao Liu <zhao1.liu@intel.com>
> ---
> docs/devel/qom.rst | 11 +----------
> 1 file changed, 1 insertion(+), 10 deletions(-)
>
> diff --git a/docs/devel/qom.rst b/docs/devel/qom.rst
> index 5870745ba27b..185f4c2f5921 100644
> --- a/docs/devel/qom.rst
> +++ b/docs/devel/qom.rst
> @@ -326,21 +326,12 @@ This is equivalent to the following:
>    :caption: Expansion from declaring a simple type
>
>    typedef struct MyDevice MyDevice;
> -   typedef struct MyDeviceClass MyDeviceClass;
>
> -   G_DEFINE_AUTOPTR_CLEANUP_FUNC(MyDeviceClass, object_unref)
> +   G_DEFINE_AUTOPTR_CLEANUP_FUNC(MyDevice, object_unref)
>
> -   #define MY_DEVICE_GET_CLASS(void *obj) \
> -           OBJECT_GET_CLASS(MyDeviceClass, obj, TYPE_MY_DEVICE)
> -   #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;
> -   };
> -
> 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

Maybe you need to adjust the text here about OBJECT_DECLARE_TYPE here and 
show how to define Class sturct?

Regards,
BALATON Zoltan

Re: [PATCH 2/9] docs/devel/qom: Fix the doc about OBJECT_DECLARE_SIMPLE_TYPE

Posted by Zhao Liu 6 months ago

On Wed, May 14, 2025 at 02:06:14PM +0200, BALATON Zoltan wrote:
> Date: Wed, 14 May 2025 14:06:14 +0200
> From: BALATON Zoltan <balaton@eik.bme.hu>
> Subject: Re: [PATCH 2/9] docs/devel/qom: Fix the doc about
>  OBJECT_DECLARE_SIMPLE_TYPE
> 
> On Wed, 14 May 2025, Zhao Liu wrote:
> > Currently, the expansion example of OBJECT_DECLARE_SIMPLE_TYPE "roughly"
> > reflects what OBJECT_DECLARE_TYPE is doing.
> > 
> > Why "roughly"? Because this line -
> > 
> > >    G_DEFINE_AUTOPTR_CLEANUP_FUNC(MyDeviceClass, object_unref)
> > 
> > - is also wrong for OBJECT_DECLARE_TYPE.
> > 
> > Fix the expansion example of OBJECT_DECLARE_SIMPLE_TYPE, especially
> > drop that definition of MyDeviceClass.
> > 
> > Cc: Paolo Bonzini <pbonzini@redhat.com>
> > Cc: "Daniel P. Berrangé" <berrange@redhat.com>
> > Cc: Eduardo Habkost <eduardo@habkost.net>
> > Signed-off-by: Zhao Liu <zhao1.liu@intel.com>
> > ---
> > docs/devel/qom.rst | 11 +----------
> > 1 file changed, 1 insertion(+), 10 deletions(-)
> > 
> > diff --git a/docs/devel/qom.rst b/docs/devel/qom.rst
> > index 5870745ba27b..185f4c2f5921 100644
> > --- a/docs/devel/qom.rst
> > +++ b/docs/devel/qom.rst
> > @@ -326,21 +326,12 @@ This is equivalent to the following:
> >    :caption: Expansion from declaring a simple type
> > 
> >    typedef struct MyDevice MyDevice;
> > -   typedef struct MyDeviceClass MyDeviceClass;
> > 
> > -   G_DEFINE_AUTOPTR_CLEANUP_FUNC(MyDeviceClass, object_unref)
> > +   G_DEFINE_AUTOPTR_CLEANUP_FUNC(MyDevice, object_unref)
> > 
> > -   #define MY_DEVICE_GET_CLASS(void *obj) \
> > -           OBJECT_GET_CLASS(MyDeviceClass, obj, TYPE_MY_DEVICE)
> > -   #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;
> > -   };
> > -
> > 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
> 
> Maybe you need to adjust the text here about OBJECT_DECLARE_TYPE here and
> show how to define Class sturct?

Then it's not easy to organize the structure in this document, since
most of the content is now make "OBJECT_DECLARE_SIMPLE_TYPE" as well as
"OBJECT_DEFINE_SIMPLE_TYPE" as examples... I'm a bit unsure, and we can
wait and see what others would say.

BTW, I found I missed this sentence:

"(OBJECT_DECLARE_TYPE) This does the same as OBJECT_DECLARE_SIMPLE_TYPE(),
but without the 'struct MyDeviceClass' definition."

It should be: This does the same as OBJECT_DECLARE_SIMPLE_TYPE(),
but with the class type.

Thanks,
Zhao

Re: [PATCH 2/9] docs/devel/qom: Fix the doc about OBJECT_DECLARE_SIMPLE_TYPE

Posted by BALATON Zoltan 6 months ago

On Wed, 14 May 2025, Zhao Liu wrote:
> On Wed, May 14, 2025 at 02:06:14PM +0200, BALATON Zoltan wrote:
>> Date: Wed, 14 May 2025 14:06:14 +0200
>> From: BALATON Zoltan <balaton@eik.bme.hu>
>> Subject: Re: [PATCH 2/9] docs/devel/qom: Fix the doc about
>>  OBJECT_DECLARE_SIMPLE_TYPE
>>
>> On Wed, 14 May 2025, Zhao Liu wrote:
>>> Currently, the expansion example of OBJECT_DECLARE_SIMPLE_TYPE "roughly"
>>> reflects what OBJECT_DECLARE_TYPE is doing.
>>>
>>> Why "roughly"? Because this line -
>>>
>>>>    G_DEFINE_AUTOPTR_CLEANUP_FUNC(MyDeviceClass, object_unref)
>>>
>>> - is also wrong for OBJECT_DECLARE_TYPE.
>>>
>>> Fix the expansion example of OBJECT_DECLARE_SIMPLE_TYPE, especially
>>> drop that definition of MyDeviceClass.
>>>
>>> Cc: Paolo Bonzini <pbonzini@redhat.com>
>>> Cc: "Daniel P. Berrangé" <berrange@redhat.com>
>>> Cc: Eduardo Habkost <eduardo@habkost.net>
>>> Signed-off-by: Zhao Liu <zhao1.liu@intel.com>
>>> ---
>>> docs/devel/qom.rst | 11 +----------
>>> 1 file changed, 1 insertion(+), 10 deletions(-)
>>>
>>> diff --git a/docs/devel/qom.rst b/docs/devel/qom.rst
>>> index 5870745ba27b..185f4c2f5921 100644
>>> --- a/docs/devel/qom.rst
>>> +++ b/docs/devel/qom.rst
>>> @@ -326,21 +326,12 @@ This is equivalent to the following:
>>>    :caption: Expansion from declaring a simple type
>>>
>>>    typedef struct MyDevice MyDevice;
>>> -   typedef struct MyDeviceClass MyDeviceClass;
>>>
>>> -   G_DEFINE_AUTOPTR_CLEANUP_FUNC(MyDeviceClass, object_unref)
>>> +   G_DEFINE_AUTOPTR_CLEANUP_FUNC(MyDevice, object_unref)
>>>
>>> -   #define MY_DEVICE_GET_CLASS(void *obj) \
>>> -           OBJECT_GET_CLASS(MyDeviceClass, obj, TYPE_MY_DEVICE)
>>> -   #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;
>>> -   };
>>> -
>>> 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
>>
>> Maybe you need to adjust the text here about OBJECT_DECLARE_TYPE here and
>> show how to define Class sturct?
>
> Then it's not easy to organize the structure in this document, since
> most of the content is now make "OBJECT_DECLARE_SIMPLE_TYPE" as well as
> "OBJECT_DEFINE_SIMPLE_TYPE" as examples... I'm a bit unsure, and we can
> wait and see what others would say.
>
> BTW, I found I missed this sentence:
>
> "(OBJECT_DECLARE_TYPE) This does the same as OBJECT_DECLARE_SIMPLE_TYPE(),
> but without the 'struct MyDeviceClass' definition."
>
> It should be: This does the same as OBJECT_DECLARE_SIMPLE_TYPE(),
> but with the class type.

Yes that's what I meant. If you remove the class example then how will 
readers know how to define that so a new example for that may be needed 
but you can wait for others' opinion too.

Regards,
BALATON Zoltan

Re: [PATCH 2/9] docs/devel/qom: Fix the doc about OBJECT_DECLARE_SIMPLE_TYPE

Posted by Zhao Liu 6 months ago

On Wed, May 14, 2025 at 06:16:31PM +0200, BALATON Zoltan wrote:
> Date: Wed, 14 May 2025 18:16:31 +0200
> From: BALATON Zoltan <balaton@eik.bme.hu>
> Subject: Re: [PATCH 2/9] docs/devel/qom: Fix the doc about
>  OBJECT_DECLARE_SIMPLE_TYPE
> 
> On Wed, 14 May 2025, Zhao Liu wrote:
> > On Wed, May 14, 2025 at 02:06:14PM +0200, BALATON Zoltan wrote:
> > > Date: Wed, 14 May 2025 14:06:14 +0200
> > > From: BALATON Zoltan <balaton@eik.bme.hu>
> > > Subject: Re: [PATCH 2/9] docs/devel/qom: Fix the doc about
> > >  OBJECT_DECLARE_SIMPLE_TYPE
> > > 
> > > On Wed, 14 May 2025, Zhao Liu wrote:
> > > > Currently, the expansion example of OBJECT_DECLARE_SIMPLE_TYPE "roughly"
> > > > reflects what OBJECT_DECLARE_TYPE is doing.
> > > > 
> > > > Why "roughly"? Because this line -
> > > > 
> > > > >    G_DEFINE_AUTOPTR_CLEANUP_FUNC(MyDeviceClass, object_unref)
> > > > 
> > > > - is also wrong for OBJECT_DECLARE_TYPE.
> > > > 
> > > > Fix the expansion example of OBJECT_DECLARE_SIMPLE_TYPE, especially
> > > > drop that definition of MyDeviceClass.
> > > > 
> > > > Cc: Paolo Bonzini <pbonzini@redhat.com>
> > > > Cc: "Daniel P. Berrang?" <berrange@redhat.com>
> > > > Cc: Eduardo Habkost <eduardo@habkost.net>
> > > > Signed-off-by: Zhao Liu <zhao1.liu@intel.com>
> > > > ---
> > > > docs/devel/qom.rst | 11 +----------
> > > > 1 file changed, 1 insertion(+), 10 deletions(-)
> > > > 
> > > > diff --git a/docs/devel/qom.rst b/docs/devel/qom.rst
> > > > index 5870745ba27b..185f4c2f5921 100644
> > > > --- a/docs/devel/qom.rst
> > > > +++ b/docs/devel/qom.rst
> > > > @@ -326,21 +326,12 @@ This is equivalent to the following:
> > > >    :caption: Expansion from declaring a simple type
> > > > 
> > > >    typedef struct MyDevice MyDevice;
> > > > -   typedef struct MyDeviceClass MyDeviceClass;
> > > > 
> > > > -   G_DEFINE_AUTOPTR_CLEANUP_FUNC(MyDeviceClass, object_unref)
> > > > +   G_DEFINE_AUTOPTR_CLEANUP_FUNC(MyDevice, object_unref)
> > > > 
> > > > -   #define MY_DEVICE_GET_CLASS(void *obj) \
> > > > -           OBJECT_GET_CLASS(MyDeviceClass, obj, TYPE_MY_DEVICE)
> > > > -   #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;
> > > > -   };
> > > > -
> > > > 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
> > > 
> > > Maybe you need to adjust the text here about OBJECT_DECLARE_TYPE here and
> > > show how to define Class sturct?
> > 
> > Then it's not easy to organize the structure in this document, since
> > most of the content is now make "OBJECT_DECLARE_SIMPLE_TYPE" as well as
> > "OBJECT_DEFINE_SIMPLE_TYPE" as examples... I'm a bit unsure, and we can
> > wait and see what others would say.
> > 
> > BTW, I found I missed this sentence:
> > 
> > "(OBJECT_DECLARE_TYPE) This does the same as OBJECT_DECLARE_SIMPLE_TYPE(),
> > but without the 'struct MyDeviceClass' definition."
> > 
> > It should be: This does the same as OBJECT_DECLARE_SIMPLE_TYPE(),
> > but with the class type.
> 
> Yes that's what I meant. If you remove the class example then how will
> readers know how to define that so a new example for that may be needed but
> you can wait for others' opinion too.

The new example deserves another separate patch. I'll think about how to
describe it.

Thanks,
Zhao