[libvirt] RFC: fixing struct name in public header
Take a look at this def from libvirt-domain.h: typedef struct _virDomainInterfaceIPAddress virDomainIPAddress; typedef virDomainIPAddress *virDomainIPAddressPtr; struct _virDomainInterfaceIPAddress { int type; /* virIPAddrType */ char *addr; /* IP address */ unsigned int prefix; /* IP address prefix */ }; Notice the struct name is different from the typedef names. Technically renaming the struct to remove the 'Interface' word would be an API break. On the flip side though we don't expect any apps to use the struct name, but rather use the typedefs, hence use of '_' in the name. We could do what we did with the typed parameter stuff and rename the struct, but add a #define _virDomainInterfaceIPAddress _virDomainIPAddress Any thoughts ? Regards, Daniel -- |: http://berrange.com -o- http://www.flickr.com/photos/dberrange/ :| |: http://libvirt.org -o- http://virt-manager.org :| |: http://entangle-photo.org -o- http://search.cpan.org/~danberr/ :|
On 04/12/2017 01:31 PM, Daniel P. Berrange wrote:
Take a look at this def from libvirt-domain.h:
typedef struct _virDomainInterfaceIPAddress virDomainIPAddress; typedef virDomainIPAddress *virDomainIPAddressPtr; struct _virDomainInterfaceIPAddress { int type; /* virIPAddrType */ char *addr; /* IP address */ unsigned int prefix; /* IP address prefix */ };
Notice the struct name is different from the typedef names.
Technically renaming the struct to remove the 'Interface' word would be an API break.
On the flip side though we don't expect any apps to use the struct name, but rather use the typedefs, hence use of '_' in the name.
We could do what we did with the typed parameter stuff and rename the struct, but add a
#define _virDomainInterfaceIPAddress _virDomainIPAddress
Any thoughts ?
I'd rename it even without the additional #define. APPs should favour the type instead of using struct _virBlah. We have it there because there's no other way to expose the struct members to callers in C. Michal
On Wed, Apr 12, 2017 at 03:01:35PM +0200, Michal Privoznik wrote:
On 04/12/2017 01:31 PM, Daniel P. Berrange wrote:
Take a look at this def from libvirt-domain.h:
typedef struct _virDomainInterfaceIPAddress virDomainIPAddress; typedef virDomainIPAddress *virDomainIPAddressPtr; struct _virDomainInterfaceIPAddress { int type; /* virIPAddrType */ char *addr; /* IP address */ unsigned int prefix; /* IP address prefix */ };
Notice the struct name is different from the typedef names.
Technically renaming the struct to remove the 'Interface' word would be an API break.
On the flip side though we don't expect any apps to use the struct name, but rather use the typedefs, hence use of '_' in the name.
We could do what we did with the typed parameter stuff and rename the struct, but add a
#define _virDomainInterfaceIPAddress _virDomainIPAddress
Any thoughts ?
I'd rename it even without the additional #define. APPs should favour the type instead of using struct _virBlah. We have it there because there's no other way to expose the struct members to callers in C.
That's true but it could break some application and libvirt promises not to do that, so I'm for the rename including the #define. We cannot assume that it's not used and simply rename it. This might be related, but how about marking some our really old API and also those wrong names as deprecated or some different compile time warning to let developers know that they might want to update their code? Pavel
On 04/12/2017 03:07 PM, Pavel Hrdina wrote:
On Wed, Apr 12, 2017 at 03:01:35PM +0200, Michal Privoznik wrote:
On 04/12/2017 01:31 PM, Daniel P. Berrange wrote:
Take a look at this def from libvirt-domain.h:
typedef struct _virDomainInterfaceIPAddress virDomainIPAddress; typedef virDomainIPAddress *virDomainIPAddressPtr; struct _virDomainInterfaceIPAddress { int type; /* virIPAddrType */ char *addr; /* IP address */ unsigned int prefix; /* IP address prefix */ };
Notice the struct name is different from the typedef names.
Technically renaming the struct to remove the 'Interface' word would be an API break.
On the flip side though we don't expect any apps to use the struct name, but rather use the typedefs, hence use of '_' in the name.
We could do what we did with the typed parameter stuff and rename the struct, but add a
#define _virDomainInterfaceIPAddress _virDomainIPAddress
Any thoughts ?
I'd rename it even without the additional #define. APPs should favour the type instead of using struct _virBlah. We have it there because there's no other way to expose the struct members to callers in C.
That's true but it could break some application and libvirt promises not to do that, so I'm for the rename including the #define. We cannot assume that it's not used and simply rename it.
I don't think I see how this would break applications. ABI stays the same. API - well, if they use struct _virDomainInterfaceIPAddess directly, they are going to need to fix that. On the other hand, they shouldn't be using it in the first place.
This might be related, but how about marking some our really old API and also those wrong names as deprecated or some different compile time warning to let developers know that they might want to update their code?
While I would like that, what APIs do you think we should mark as deprecated? Because I usually use old APIs when I don't need anything fancy (e.g. flags). Michal
On Wed, Apr 12, 2017 at 12:31:51PM +0100, Daniel P. Berrange wrote:
Take a look at this def from libvirt-domain.h:
typedef struct _virDomainInterfaceIPAddress virDomainIPAddress; typedef virDomainIPAddress *virDomainIPAddressPtr; struct _virDomainInterfaceIPAddress { int type; /* virIPAddrType */ char *addr; /* IP address */ unsigned int prefix; /* IP address prefix */ };
Notice the struct name is different from the typedef names.
Technically renaming the struct to remove the 'Interface' word would be an API break.
On the flip side though we don't expect any apps to use the struct name, but rather use the typedefs, hence use of '_' in the name.
Yeah, also if you look at the documentation [1], we use the typedef name even for the struct name (strictly technically wrong). The _virDomainInterfaceIPAddress is used in one place there and hence, in my opinion, it is not a breakage if we *just* rename it. [1] http://libvirt.org/html/libvirt-libvirt-domain.html#virDomainIPAddress
We could do what we did with the typed parameter stuff and rename the struct, but add a
#define _virDomainInterfaceIPAddress _virDomainIPAddress
Any thoughts ?
Regards, Daniel -- |: http://berrange.com -o- http://www.flickr.com/photos/dberrange/ :| |: http://libvirt.org -o- http://virt-manager.org :| |: http://entangle-photo.org -o- http://search.cpan.org/~danberr/ :|
-- libvir-list mailing list libvir-list@redhat.com https://www.redhat.com/mailman/listinfo/libvir-list
participants (4)
-
Daniel P. Berrange -
Martin Kletzander -
Michal Privoznik -
Pavel Hrdina