On Tue, Mar 11, 2025 at 14:24:28 +0000, Daniel P. Berrangé wrote: > Give an overview of how arrays are handled and represented in > the typed parameters returned by the guest info API. > > Signed-off-by: Daniel P. Berrangé <berrange@xxxxxxxxxx> > --- > src/libvirt-domain.c | 50 ++++++++++++++++++++++++++++++++++++++++++++ > 1 file changed, 50 insertions(+) > > diff --git a/src/libvirt-domain.c b/src/libvirt-domain.c > index 5bb9f3895e..59fb923d10 100644 > --- a/src/libvirt-domain.c > +++ b/src/libvirt-domain.c > @@ -12390,6 +12390,56 @@ virConnectGetDomainCapabilities(virConnectPtr conn, > * VIR_CONNECT_GET_ALL_DOMAINS_STATS_SHUTOFF and/or > * VIR_CONNECT_GET_ALL_DOMAINS_STATS_OTHER for all other states. > * > + * In a number of cases the parameters returned are representing > + * arrays of data items. In these cases multiple VIR_DOMAIN_GUEST_INFO* The constant names are for the guest stats ... > + * constants will need to be concatenated to form a complete typed > + * parameter key. The design pattern for handling array entries is > + * as follows > + * > + * - VIR_DOMAIN_GUEST_INFO_nnnnn_COUNT ... > + * > + * Defines the upper limit on the number of elements that will > + * be returned. In some cases the array information may be > + * sparsely populated, so it is not considered an error if a > + * given element does not exist. Applications should check for > + * each possible element upto the declared limit. > + * > + * - VIR_DOMAIN_GUEST_INFO_nnnnn_PREFIX ... > + * > + * Defines the prefix to be used to construct the typed parameter > + * key for an array element, including the trailing '.'. The prefix > + * must have an array index appended, along with a suffix. > + * > + * - VIR_DOMAIN_GUEST_INFO_nnnnn_SUFFIX_mmmmm ... > + * > + * Defines the suffix for accessing a particular data item within > + * the array element, including the leading '.'. The suffix must > + * have an array prefix and index prepended. > + * > + * As an example, assuming a printf-like formatting approach an > + * application would construct a key as follows: > + * > + * format(VIR_DOMAIN_STATS_CPU_CACHE_MONITOR_PREFIX + > + * "%d" + > + * VIR_DOMAIN_STATS_CPU_CACHE_MONITOR_SUFFIX_VCPUS > + * index) Here it's okay. > + * > + * Which, when index==3, would result in the key "cpu.cache.monitor.3.vcpus" > + * > + * In some cases there may be nested arrays, in which case the key > + * is formed by concatenating multiple prefixes and suffixes with > + * mutliple array indexes. For example: > + * > + * format(VIR_DOMAIN_STATS_CPU_CACHE_MONITOR_PREFIX + > + * "%d" + > + * VIR_DOMAIN_STATS_CPU_CACHE_MONITOR_SUFFIX_BANK_PREFIX + > + * "%d" + > + * VIR_DOMAIN_STATS_CPU_CACHE_MONITOR_SUFFIX_BANK_SUFFIX_BYTES > + * monindex, bankindex) > + * > + * Which, when monindex==3 and bankindex==7, would result in the > + * key "cpu.cache.monitor.3.bank.7.bytes". > + * > * Returns the count of returned statistics structures on success, -1 on error. > * The requested data are returned in the @retStats parameter. The returned > * array should be freed by the caller. See virDomainStatsRecordListFree. > -- > 2.48.1 > Reviewed-by: Peter Krempa <pkrempa@xxxxxxxxxx>
