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@xxxxxxxxxx>
> ---
> 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.
Kevin
