Contrary to most APIs returning typed parameters, there are no constants
defined for the domain stats data keys. This is was because many of the
keys needs to be dynamically constructed using one or more array index
values.
It is possible to define constants while still supporting dynamic
array indexes by simply defining the prefixes and suffixes as constants.
The consuming code can then combine the constants with array index
value.
With this approach, it is practical to add constants for the domain stats
API keys.
The pattern for array entries is as follows
* VIR_DOMAIN_GUEST_INFO_blah_COUNT - the number of items in the array
* VIR_DOMAIN_GUEST_INFO_blah_PREFIX - the key prefix, including the
trailing '.' - eg "disk."
* VIR_DOMAIN_GUEST_INFO_blah_SUFFIX_blah - the key suffix, including
the leading '.' - eg ".name"
Where there are nested arrays, this repeats in the natural way
* VIR_DOMAIN_GUEST_INFO_blah_SUFFIX_blah_COUNT - the number of items in the array
* VIR_DOMAIN_GUEST_INFO_blah_SUFFIX_blah_PREFIX - the key prefix, including the
leading and trailing '.' - eg ".addr."
* VIR_DOMAIN_GUEST_INFO_blah_SUFFIX_blah_SUFFIX_blah - the key suffix, including
the leading '.' - eg ".name"
A usage of this would look like, relying on CPP string concatenation
asprintf(&str, VIR_DOMAIN_STATS_VCPU_PREFIX "%d" VIR_DOMAIN_STATS_VCPU_SUFFIX_DELAY, idx);
Or in language bindings such as Golang
fmt.Sprintf(C.VIR_DOMAIN_STATS_VCPU_PREFIX+"%d"+C.VIR_DOMAIN_STATS_VCPU_SUFFIX_HALTED, idx)
Adding these constants has a few benefits:
* We can ensure that different drivers are all consistent in keys
used for typed parameters
* Language bindings can query the API XML to identify any gaps
in their API coverage
A note on "Since" tags. We use the "Since" tags to express when an API
was added to libvirt. In this case we're adding constants long /after/
we first introduced these APIs. So the question is whether the Since
tags reflect when the typed parameter key was first used or when the
API constant was added.
For convenience I chose the latter, because the Golang bnidings use
the Since tags to auto generate code with #if !LIBVIRT_CHECK_VERSION()
around its usage of the constants. This would break if we retroactively
dated the Since tags to when the keys were first used.
As proof of the value, adding these constants has lead to be find
sooooooooooo many mistakes in the Golang bindings where we forgot
to add new domain stats/guest info data items, and one place where
we typod the name.
Daniel P. Berrangé (19):
src: add constants for guest info 'user.' parameters
src: add constants for guest info 'os.' parameters
src: add constants for guest info 'timezone.' parameters
src: add constant for the guest info 'hostname' parameter
src: add constants for guest info 'fs.' parameters
src: add constants for guest info 'disk.' parameters
src: add constants for guest info 'if.' parameters
src: add constants for domain stats 'state.' parameters
src: add constants for domain stats 'cpu.' parameters
src: add constants for domain stats 'balloon.' parameters
src: add constants for domain stats 'vcpu.' parameters
src: add constants for domain stats 'net.' parameters
src: add constants for domain stats 'block.' parameters
src: add constants for domain stats 'perf.' parameters
src: add constants for domain stats 'iothread.' parameters
src: add constants for domain stats 'memory.' parameters
src: add constants for domain stats 'dirtyrate.' parameters
src: add constants for domain stats 'dirtyrate.' parameters
src: document that no constants are provided for custom VM stats
include/libvirt/libvirt-domain.h | 1614 ++++++++++++++++++++++++++++++
src/libvirt-domain.c | 424 ++------
src/qemu/qemu_agent.c | 36 +-
src/qemu/qemu_driver.c | 425 +++++---
4 files changed, 1996 insertions(+), 503 deletions(-)
--
2.48.1