On Tue, Mar 04, 2025 at 14:51:55 +0000, Daniel P. Berrangé wrote:
> On Tue, Mar 04, 2025 at 03:48:51PM +0100, Peter Krempa wrote:
> > On Tue, Mar 04, 2025 at 14:04:03 +0000, Daniel P. Berrangé wrote:
> > > 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.
> > >
> > > Signed-off-by: Daniel P. Berrangé <berrange@xxxxxxxxxx>
> > > ---
> > > include/libvirt/libvirt-domain.h | 20 ++++++++++++++++++++
> > > src/libvirt-domain.c | 9 +++------
> > > src/qemu/qemu_driver.c | 6 ++++--
> > > 3 files changed, 27 insertions(+), 8 deletions(-)
> > >
> > > diff --git a/include/libvirt/libvirt-domain.h b/include/libvirt/libvirt-domain.h
> > > index 1d988daf96..5b014adcd0 100644
> > > --- a/include/libvirt/libvirt-domain.h
> > > +++ b/include/libvirt/libvirt-domain.h
> > > @@ -2782,6 +2782,26 @@ struct _virDomainStatsRecord {
> > > int nparams;
> > > };
> > >
> > > +
> > > +/**
> > > + * VIR_DOMAIN_STATS_STATE_STATE:
> > > + *
> > > + * State of the VM, returned as int from virDomainState enum.
> > > + *
> > > + * Since: 11.2.0
> >
> > As noted in my reply to 1/19, I think we need some wording saying that
> > for the legacy constants that are being added the 'since' field applies
> > only on when the constant was added but not since when the data is
> > available.
>
> If we did the archeology we could do
>
> "Since: 11.2.0 (constant only, data since 8.2.0)"
>
> but would need to hack our API build script to ignore stuff
> in the (...) brackets ?
Given that it wasn't versioned before we could possibly also document
e.g. at the function docs block that 'anything 11.2.0' is when the
constant was introduced; but doesn't necessarily mean that it's when the
data is present.
Both APIs explicitly allow individual fields to be missing based on a
variety of factors so it's not like the user can rely on the data in any
way.
