[PATCH v2 21/23] src: document that no constants are provided for custom VM stats
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.
Reviewed-by: Peter Krempa <pkrempa(a)redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange(a)redhat.com>
---
include/libvirt/libvirt-domain.h | 12 ++++++++++++
src/libvirt-domain.c | 12 +++++-------
2 files changed, 17 insertions(+), 7 deletions(-)
diff --git a/include/libvirt/libvirt-domain.h b/include/libvirt/libvirt-domain.h
index ba5a0c1b9a..edf9c6f625 100644
--- a/include/libvirt/libvirt-domain.h
+++ b/include/libvirt/libvirt-domain.h
@@ -3918,6 +3918,18 @@ struct _virDomainStatsRecord {
*/
#define VIR_DOMAIN_STATS_DIRTYRATE_VCPU_SUFFIX_MEGABYTES_PER_SECOND
".megabytes_per_second"
+
+/**
+ * VIR_DOMAIN_STATS_VM_PREFIX:
+ *
+ * Concatenate the prefix, a hypervisor specific custom stats name and one
+ * of the VIR_DOMAIN_STATS_CUSTOM_TYPE_* constants to form a complete
+ * parameter name
+ *
+ * Since: 11.2.0
+ */
+#define VIR_DOMAIN_STATS_VM_PREFIX "vm."
+
/**
* virDomainStatsTypes:
*
diff --git a/src/libvirt-domain.c b/src/libvirt-domain.c
index 481a1833de..5bb9f3895e 100644
--- a/src/libvirt-domain.c
+++ b/src/libvirt-domain.c
@@ -12335,14 +12335,12 @@ virConnectGetDomainCapabilities(virConnectPtr conn,
*
* "vm.$NAME.$TYPE"
*
- * $NAME - name of the statistics field provided by the hypervisor
- *
- * $TYPE - Type of the value. The following types are returned:
- * 'cur' - current instant value
- * 'sum' - aggregate value
- * 'max' - peak value
+ * Where $NAME is an arbitrary choice of the hypervisor driver, for
+ * which no API constants are defined.
+ * The $TYPE values are defined by VIR_DOMAIN_STATS_CUSTOM_TYPE_*
+ * constants.
*
- * The returned value may be either an unsigned long long or a boolean.
+ * The returned value may be either an unsigned long long or a boolean.
*
* WARNING:
* The stats reported in this group are runtime-collected and
--
2.48.1