Re: [Libguestfs] [PATCH v2 1/5] qapi: Enable enum member introspection to show more than name

Am 09.10.2021 um 14:09 hat Markus Armbruster geschrieben: > The next commit will add feature flags to enum members. There's a > problem, though: query-qmp-schema shows an enum type's members as an > array of member names (SchemaInfoEnum member @values). If it showed > an array of objects with a name member, we could simply add more > members to these objects. Since it's just strings, we can't. > > I can see three ways to correct this design mistake: > > 1. Do it the way we should have done it, plus compatibility goo. > > We want a ['SchemaInfoEnumMember'] member in SchemaInfoEnum. Since > changing @values would be a compatibility break, add a new member > @members instead. > > @values is now redundant. In my testing, output of > qemu-system-x86_64's query-qmp-schema grows by 11% (18.5KiB). > > We can deprecate @values now and drop it later. This will break > outmoded clients. Well-behaved clients such as libvirt are > expected to break cleanly. > > 2. Like 1, but omit "boring" elements of @member, and empty @member. > > @values does not become redundant. @members augments it. Somewhat > cumbersome, but output of query-qmp-schema grows only as we make > enum members non-boring. > > There is nothing to deprecate here. > > 3. Versioned query-qmp-schema. > > query-qmp-schema provides either @values or @members. The QMP > client can select which version it wants. There is no redundant > output. > > We can deprecate old versions and eventually drop them. This will > break outmoded clients. Breaking cleanly is easier than for 1. > > While 1 and 2 operate within the common rules for compatible > evolution apply (section "Compatibility considerations" in > docs/devel/qapi-code-gen.rst), 3 bypasses them. Attractive when > operating within the rules is just too awkward. Not the case here. > > This commit implements 1. Libvirt developers prefer it. > > Signed-off-by: Markus Armbruster <armbru(a)redhat.com&gt; > --- > qapi/introspect.json | 21 +++++++++++++++++++-- > scripts/qapi/introspect.py | 18 ++++++++++++++---- > 2 files changed, 33 insertions(+), 6 deletions(-) docs/devel/qapi-code-gen.rst still says: The SchemaInfo for an enumeration type has meta-type "enum" and variant member "values". The values are listed in no particular order; clients must search the entire enum when learning whether a particular value is supported. Example: the SchemaInfo for MyEnum from section `Enumeration types`_ :: { "name": "MyEnum", "meta-type": "enum", "values": [ "value1", "value2", "value3" ] } It probably needs an update.