[libvirt] virDomainInterfaceStats why is there a size?

[Richard W.M. Jones]

On Tue, Aug 12, 2008 at 01:55:26PM +0200, Stefan de Konink wrote:
> Another simple question, what is the reasoning about the size field in
> this call. I would really be a happy boy if anyone said:
> 
> if you put in path == NULL, it will fill your stats structure up to size
> interfaces.
> 
> ...but since this is not the case (yet) what is the reason behind it?

Sorry, I've only just noticed this question coming up.

The size parameter is nothing to do with how many StatsPtr structures
it can return.  This function can only ever fill in the contents of 1
structure.

Unfortunately to get stats structures for all interfaces, you have to
parse the domain XML to get the interface names.  This sucks greatly,
but there it is.  A while back I added an experimental call
virConnectListAllDomains.  I really need to get this in shape again
and add other calls to avoid having to parse XML ...
http://www.redhat.com/archives/libvir-list/2008-September/msg00077.html

So what is 'size' for?  It's to provide backwards and forwards ABI
compatibility in case we decide to add new fields to the
virDomainInterfaceStatStruct in future.  Let's imagine that at some
point in the future we decided to add an extra 8 byte field to this
structure, taking it from the current 64 byte size to 72 bytes in
size.  We have to account for two possibilities:

(1) A program is compiled against an older libvirt, but linked
(dynamically) to a newer libvirt.

(2) A program is compiled against a newer libvirt, but linked to an
older libvirt.

In each case, libvirt is able to do the Right Thing.  In case (1), the
program will pass size = 64.  The newer libvirt will truncate the
stats that it returns to 64 bytes, so it doesn't write garbage beyond
the end of the structure.

In case (2), the program will pass size = 72.  The older (ie. current)
libvirt understands this and will only write 64 bytes of data to the
structure.  (In this case, the program has the choice over whether it
wishes to detect this situation -- which it can do by writing some
canard value to the extra fields in the structure).

Rich.

-- 
Richard Jones, Emerging Technologies, Red Hat  http://et.redhat.com/~rjones
virt-top is 'top' for virtual machines.  Tiny program with many
powerful monitoring features, net stats, disk stats, logging, etc.
http://et.redhat.com/~rjones/virt-top